diff --git a/404.html b/404.html index 1cc00d9d022..d6777e49650 100644 --- a/404.html +++ b/404.html @@ -5,13 +5,13 @@ Page Not Found | Rancher Manager - +
Skip to main content

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/assets/js/e926511c.42ab8cd7.js b/assets/js/e926511c.42ab8cd7.js new file mode 100644 index 00000000000..a44d7608c4d --- /dev/null +++ b/assets/js/e926511c.42ab8cd7.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkrancher_docs=self.webpackChunkrancher_docs||[]).push([[79187],{3905:function(e,t,n){n.d(t,{Zo:function(){return p},kt:function(){return m}});var a=n(67294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function o(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=a.createContext({}),s=function(e){var t=a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},p=function(e){var t=s(e.components);return a.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,c=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=s(n),m=r,k=u["".concat(c,".").concat(m)]||u[m]||d[m]||i;return n?a.createElement(k,o(o({ref:t},p),{},{components:n})):a.createElement(k,o({ref:t},p))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=u;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var s=2;s\n secretKey: \n")),(0,i.kt)("div",{className:"admonition admonition-note alert alert--secondary"},(0,i.kt)("div",{parentName:"div",className:"admonition-heading"},(0,i.kt)("h5",{parentName:"div"},(0,i.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,i.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"}))),"note")),(0,i.kt)("div",{parentName:"div",className:"admonition-content"},(0,i.kt)("p",{parentName:"div"},"To avoid encoding issues, the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecret")," can be created with the below command, updating the values for ",(0,i.kt)("inlineCode",{parentName:"p"},"accessKey")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"secretKey"),"."),(0,i.kt)("pre",{parentName:"div"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl create secret generic s3-creds \\\n --from-literal=accessKey= \\\n --from-literal=secretKey=\n")))),(0,i.kt)("h3",{id:"iam-permissions-for-ec2-nodes-to-access-s3"},"IAM Permissions for EC2 Nodes to Access S3"),(0,i.kt)("p",null,"There are two ways to set up the ",(0,i.kt)("inlineCode",{parentName:"p"},"rancher-backup")," operator to use S3 as the backup storage location."),(0,i.kt)("p",null,"One way is to configure the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecretName")," in the Backup custom resource, which refers to AWS credentials that have access to S3."),(0,i.kt)("p",null,"If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3."),(0,i.kt)("p",null,"To allow a node to access S3, follow the instructions in the ",(0,i.kt)("a",{parentName:"p",href:"https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/"},"AWS documentation")," to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the ",(0,i.kt)("inlineCode",{parentName:"p"},"Resource")," with your bucket name:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Effect": "Allow",\n "Action": [\n "s3:ListBucket"\n ],\n "Resource": [\n "arn:aws:s3:::rancher-backups"\n ]\n },\n {\n "Effect": "Allow",\n "Action": [\n "s3:PutObject",\n "s3:GetObject",\n "s3:DeleteObject",\n "s3:PutObjectAcl"\n ],\n "Resource": [\n "arn:aws:s3:::rancher-backups/*"\n ]\n }\n ]\n}\n')),(0,i.kt)("p",null,"After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecretName")," directive can be left empty in the Backup custom resource."),(0,i.kt)("h2",{id:"examples"},"Examples"),(0,i.kt)("p",null,"For example Backup custom resources, refer to ",(0,i.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/examples#backup"},"this page.")))}m.isMDXComponent=!0},61687:function(e,t,n){t.Z=n.p+"assets/images/encryption-764e07a9a1c79ccb857802bdba719cb8.png"}}]); \ No newline at end of file diff --git a/assets/js/e926511c.98537e0b.js b/assets/js/e926511c.98537e0b.js deleted file mode 100644 index 68d8c284c12..00000000000 --- a/assets/js/e926511c.98537e0b.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkrancher_docs=self.webpackChunkrancher_docs||[]).push([[79187],{3905:function(e,t,n){n.d(t,{Zo:function(){return p},kt:function(){return m}});var a=n(67294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,a)}return n}function o(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var c=a.createContext({}),s=function(e){var t=a.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):o(o({},t),e)),n},p=function(e){var t=s(e.components);return a.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var n=e.components,r=e.mdxType,i=e.originalType,c=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=s(n),m=r,k=u["".concat(c,".").concat(m)]||u[m]||d[m]||i;return n?a.createElement(k,o(o({ref:t},p),{},{components:n})):a.createElement(k,o({ref:t},p))}));function m(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=n.length,o=new Array(i);o[0]=u;var l={};for(var c in t)hasOwnProperty.call(t,c)&&(l[c]=t[c]);l.originalType=e,l.mdxType="string"==typeof e?e:r,o[1]=l;for(var s=2;s\n secretKey: \n")),(0,i.kt)("div",{className:"admonition admonition-note alert alert--secondary"},(0,i.kt)("div",{parentName:"div",className:"admonition-heading"},(0,i.kt)("h5",{parentName:"div"},(0,i.kt)("span",{parentName:"h5",className:"admonition-icon"},(0,i.kt)("svg",{parentName:"span",xmlns:"http://www.w3.org/2000/svg",width:"14",height:"16",viewBox:"0 0 14 16"},(0,i.kt)("path",{parentName:"svg",fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"}))),"note")),(0,i.kt)("div",{parentName:"div",className:"admonition-content"},(0,i.kt)("p",{parentName:"div"},"To avoid encoding issues, the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecret")," can be created with the below command, updating the values for ",(0,i.kt)("inlineCode",{parentName:"p"},"accessKey")," and ",(0,i.kt)("inlineCode",{parentName:"p"},"secretKey"),"."),(0,i.kt)("pre",{parentName:"div"},(0,i.kt)("code",{parentName:"pre",className:"language-bash"},"kubectl create secret generic s3-creds \\\n --from-literal=accessKey= \\\n --from-literal=secretKey=\n")))),(0,i.kt)("h3",{id:"iam-permissions-for-ec2-nodes-to-access-s3"},"IAM Permissions for EC2 Nodes to Access S3"),(0,i.kt)("p",null,"There are two ways to set up the ",(0,i.kt)("inlineCode",{parentName:"p"},"rancher-backup")," operator to use S3 as the backup storage location."),(0,i.kt)("p",null,"One way is to configure the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecretName")," in the Backup custom resource, which refers to AWS credentials that have access to S3."),(0,i.kt)("p",null,"If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3."),(0,i.kt)("p",null,"To allow a node to access S3, follow the instructions in the ",(0,i.kt)("a",{parentName:"p",href:"https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/"},"AWS documentation")," to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the ",(0,i.kt)("inlineCode",{parentName:"p"},"Resource")," with your bucket name:"),(0,i.kt)("pre",null,(0,i.kt)("code",{parentName:"pre",className:"language-json"},'{\n "Version": "2012-10-17",\n "Statement": [\n {\n "Effect": "Allow",\n "Action": [\n "s3:ListBucket"\n ],\n "Resource": [\n "arn:aws:s3:::rancher-backups"\n ]\n },\n {\n "Effect": "Allow",\n "Action": [\n "s3:PutObject",\n "s3:GetObject",\n "s3:DeleteObject",\n "s3:PutObjectAcl"\n ],\n "Resource": [\n "arn:aws:s3:::rancher-backups/*"\n ]\n }\n ]\n}\n')),(0,i.kt)("p",null,"After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the ",(0,i.kt)("inlineCode",{parentName:"p"},"credentialSecretName")," directive can be left empty in the Backup custom resource."),(0,i.kt)("h2",{id:"examples"},"Examples"),(0,i.kt)("p",null,"For example Backup custom resources, refer to ",(0,i.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/examples#backup"},"this page.")))}m.isMDXComponent=!0},61687:function(e,t,n){t.Z=n.p+"assets/images/encryption-764e07a9a1c79ccb857802bdba719cb8.png"}}]); \ No newline at end of file diff --git a/assets/js/runtime~main.f31da3a3.js b/assets/js/runtime~main.a30880d0.js similarity index 99% rename from assets/js/runtime~main.f31da3a3.js rename to assets/js/runtime~main.a30880d0.js index f45446a897c..1ba51724aa5 100644 --- a/assets/js/runtime~main.f31da3a3.js +++ b/assets/js/runtime~main.a30880d0.js @@ -1 +1 @@ -!function(){"use strict";var e,f,c,b,d,a={},t={};function n(e){var f=t[e];if(void 0!==f)return f.exports;var c=t[e]={exports:{}};return a[e].call(c.exports,c,c.exports,n),c.exports}n.m=a,e=[],n.O=function(f,c,b,d){if(!c){var a=1/0;for(u=0;u=d)&&Object.keys(n.O).every((function(e){return n.O[e](c[r])}))?c.splice(r--,1):(t=!1,d0&&e[u-1][2]>d;u--)e[u]=e[u-1];e[u]=[c,b,d]},n.n=function(e){var f=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(f,{a:f}),f},c=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},n.t=function(e,b){if(1&b&&(e=this(e)),8&b)return e;if("object"==typeof e&&e){if(4&b&&e.__esModule)return e;if(16&b&&"function"==typeof e.then)return e}var d=Object.create(null);n.r(d);var a={};f=f||[null,c({}),c([]),c(c)];for(var t=2&b&&e;"object"==typeof t&&!~f.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((function(f){a[f]=function(){return e[f]}}));return a.default=function(){return e},n.d(d,a),d},n.d=function(e,f){for(var c in f)n.o(f,c)&&!n.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:f[c]})},n.f={},n.e=function(e){return Promise.all(Object.keys(n.f).reduce((function(f,c){return n.f[c](e,f),f}),[]))},n.u=function(e){return"assets/js/"+({92:"8996d840",151:"3fe327d9",218:"c2d822c0",426:"e81f13ad",470:"c4a66de2",543:"4dd994d7",560:"8773a1b3",692:"c524dfc1",803:"a8537194",858:"079e1e8c",876:"31dc42bc",1014:"9285fddf",1074:"acf37ba9",1188:"7e8c5b11",1233:"ebba9620",1272:"66e7ae78",1307:"a18d7c59",1441:"760c555d",1484:"c2f39bde",1665:"c6be4ee7",1847:"4697ba72",1995:"d9c31cac",2073:"97546b1a",2207:"0ba5f5f4",2309:"bee19150",2334:"f10d4d5c",2371:"6e9e1aa3",2463:"dd78b469",2476:"e3ab7e94",2535:"f75a5cef",2746:"288ff2ff",2786:"b6c428f4",3181:"df3f6597",3254:"b204cf5d",3260:"5672471e",3299:"c5dd4a56",3445:"11de819d",3776:"be92b392",3957:"a8523539",4180:"516de1d4",4215:"ca1329d5",4267:"bfc57044",4311:"d4fe7dbf",4397:"123b9f40",4493:"eac4d15f",4494:"99c6e5ca",4502:"58a7dbd1",4583:"1f7fe892",4589:"b650d23b",4803:"c3fb3938",4947:"6cb26668",4983:"b2bece66",5008:"4b646b93",5093:"c7fc4956",5099:"5c5b3f41",5105:"cbc79ed6",5118:"a0b4884b",5230:"febee244",5280:"92463dfc",5324:"42448ff8",5370:"4d4788cf",5418:"49d26382",5706:"f5713d99",5839:"22da2c46",5916:"94311af9",6054:"79138131",6061:"0c597aaf",6162:"95944931",6379:"6652b611",6495:"dea14605",6508:"9775b4be",6592:"d8fb889b",6617:"2f0700c3",6694:"31322e9a",6763:"bec7d502",6810:"40594ce9",7070:"ddf778e2",7297:"15045cd2",7366:"96f0cc11",7450:"4ee3153e",7573:"a04b778c",7587:"245584f2",7654:"1a00afd9",7658:"4dbeca1a",7670:"6e905236",7703:"9470bd0a",7911:"5abfffa2",8038:"40ec24e7",8092:"c99b8ea8",8145:"18e3f229",8226:"ff115ee1",8281:"d2270344",8282:"32a5bc4a",8362:"87aa1598",8392:"b7879678",8473:"28134557",8491:"0f52acfd",8562:"9692c10a",8631:"2d15e68a",8644:"55417783",8701:"0babb5d8",8769:"e57bdfae",8799:"b296451c",8899:"d50a1aa7",8901:"b7f99883",8924:"f9fdc755",8952:"16647ef7",9017:"34cd303a",9136:"26e86bf1",9324:"cabb6017",9391:"842308dc",9575:"52eba42c",9595:"c6a1800c",9613:"bec4702b",9644:"2aa62228",9712:"afde3945",9806:"d30e3ce1",9877:"c520a1a7",9899:"07df0b9e",9909:"115e2606",9981:"01a36a7a",10003:"390bc0ef",10025:"732886a8",10071:"da92d5c0",10146:"15015618",10195:"501facfc",10246:"ca63b941",10325:"de90ac60",10355:"baf47ad6",10438:"c48acb15",10557:"89b8bc8c",10571:"a6a82698",10632:"317f5e70",10814:"cfa5fe6b",10865:"cf094c24",10889:"632d2cf8",10923:"4a2eafbd",11018:"704f3734",11123:"bf37456a",11139:"fba918c0",11212:"eaaa0a94",11303:"124c01c4",11367:"60b9fd82",11405:"e8ab8a58",11532:"72b05f6d",11569:"1116174c",11785:"7b134385",11810:"cbe55200",11835:"85f56c8f",11842:"9570b89e",11955:"3e2485cd",11986:"719764be",12048:"cec2ca1b",12231:"476dfafa",12428:"389c4d39",12463:"762c1d62",12495:"ac0e4adf",12547:"da222b02",12584:"56c34b6c",12616:"db1eb9dd",12748:"2d36afb9",12752:"22cf9a33",12821:"20bedfa8",13e3:"45e55f02",13073:"0aa2529e",13085:"1f391b9e",13097:"719ba419",13134:"f527ac01",13276:"c12e27a4",13290:"7875f3e1",13297:"36f06557",13438:"5650f021",13453:"0bb2a061",13546:"2a07a4d0",13579:"8bcd2d6e",13715:"b81ecc9d",13838:"4688ce4e",14075:"279ac42b",14114:"31c44b3c",14166:"5f6facf2",14374:"47d0a33a",14418:"f85955f3",14512:"1d8e9cc6",14515:"b3807136",14525:"163f63fd",14754:"e9b3839f",14755:"5f9f26e3",14950:"bb1597c4",15090:"77b0bd90",15149:"50194363",15403:"eedf7e04",15474:"01533949",15619:"657a47a9",15640:"059f0361",15708:"a5df451c",15872:"17e07a3d",16008:"22a8b095",16137:"2239996a",16183:"5925a681",16290:"74030caf",16692:"b3e21373",16861:"ef033983",16914:"0aca2b4d",16990:"74f64fbb",17088:"70282811",17287:"f9c0e5fb",17351:"99286acb",17397:"964c8b6e",17459:"7169e4ce",17538:"89cb8e91",17659:"c38c7bb2",17670:"fa33d8d9",17726:"36d24dc3",17870:"353be3ab",18004:"4345bac2",18064:"b7117ab0",18104:"ac70c4fb",18165:"66b1ee6e",18291:"ae6d5f2a",18329:"8446b2bf",18368:"713c61ab",18428:"eb66573f",18445:"18ed944d",18617:"3b7ee216",18820:"736351cc",18846:"49c30421",18856:"6934d7e8",18911:"6781e7b1",18914:"d9f62a80",18953:"c03c4d1d",19098:"fd0c9593",19123:"643d5fb0",19179:"c2c2fd7f",19214:"f3b333b7",19218:"c7ffff18",19465:"925e00c3",19489:"53ef77ca",19510:"aed778da",19614:"26d4ccd7",19776:"68ea2107",19808:"b2e2d2bc",19853:"923177f3",20080:"6658ac42",20175:"3f076996",20334:"75f02af9",20357:"bc855d82",20425:"906a6882",20689:"97726573",20770:"31df4207",20787:"068bc51e",20988:"e17d56b8",21156:"a9683a17",21167:"65cc8405",21187:"3999cc2b",21210:"2e408315",21245:"13ecfad2",21419:"a6d2d815",21538:"529bdb84",21705:"68ad2298",21739:"ae21521b",21911:"93095eab",21931:"6227d3fc",21958:"37885d63",21981:"594057a9",22007:"4153b51e",22145:"73b78ce8",22245:"cc09ce29",22302:"21e2d8cc",22376:"39e94c6a",22460:"d07f32cc",22483:"04061093",22520:"8260111c",22546:"f7bf0eb3",22675:"eef53622",22856:"597e9a84",22894:"e4643a61",22895:"7f6c3274",23044:"ae04538d",23212:"7a30e7bf",23345:"064ee7ec",23402:"ac428ba7",23561:"011dfd7e",23791:"6228436c",23798:"37a196ea",23840:"ddc27281",24038:"5ee60ab1",24085:"0cb7b855",24242:"9baec194",24273:"fb54213f",24404:"4a870cfc",24521:"2e0b84cc",24681:"96544142",24741:"c732fadd",24836:"1907685e",24954:"d85b2a73",25215:"f573510a",25226:"d32f70f0",25279:"9e916adc",25350:"e02c1ae0",25438:"4de12aab",25567:"059e8463",25589:"05df9a2c",25863:"cb98f550",25875:"8dfc90aa",25877:"76440c84",25991:"09029ebe",26044:"639ce40f",26075:"447c27ad",26250:"ecc8df09",26283:"807ae1d8",26353:"e1f00143",26446:"83fe0eeb",26725:"d11f8d40",26743:"b8e667c5",26875:"c6ff2c51",26966:"99951bef",26976:"e647d8cd",26989:"9297bab4",27061:"2538a207",27063:"aaca71ce",27301:"41f347e6",27349:"b8b5cd27",27392:"9c496c3b",27468:"7114f94b",27557:"ed602548",27565:"11dbcd21",27656:"811b01de",27717:"d5c17d8e",27740:"ca8a26d9",27837:"ae3b439d",27918:"17896441",27987:"d189a4ea",28320:"30c0e3d1",28337:"c5969871",28491:"79a36cae",28605:"7945214a",28671:"0ac5d4d5",28768:"31f34f63",28823:"e0737014",28905:"8c39340c",28934:"0f79a30c",29143:"d4174923",29294:"497955f1",29354:"0eeb141c",29389:"154ed32a",29449:"fe10bc2e",29514:"1be78505",29617:"fb1c0286",29679:"e1caf301",29705:"b368f20d",29738:"eca70f54",29795:"6a831fa8",29797:"5612f5d2",29890:"e67f27d2",29956:"b72bc8e0",30192:"36a01650",30225:"e5c88a03",30285:"42e58cd2",30337:"e54100d7",30362:"111896fa",30382:"acc5d3e1",30394:"103fedbf",30538:"9cf07083",30575:"49423f53",30585:"df7f733d",30654:"d1838834",30685:"271c8ea4",30836:"0480b142",30949:"41875a9c",30951:"8f57dae8",31032:"f594ef05",31060:"c7376ac9",31076:"d502d095",31155:"e8c4ad4a",31190:"f710fd1b",31377:"c1dfb946",31510:"b9049539",31558:"a3b4c9e1",31732:"bd671f46",31749:"132ebbf0",31863:"2f7718d8",31869:"6ab0b16a",32163:"0700b08d",32165:"a677df94",32266:"203416e2",32356:"33aab58f",32411:"fd66e915",32513:"eb71bfd3",32527:"08736ebe",32666:"27dce654",32691:"9e504a9f",32697:"9083e0c6",32714:"d161c74d",32959:"6618d504",32991:"98580f1c",33016:"bab2a247",33017:"efd15b1e",33036:"ef2b6bbe",33083:"d4d705af",33084:"f2ae3bd8",33183:"d99ae185",33188:"ae2e7981",33296:"aa943c00",33306:"70013d1c",33458:"d077980f",33472:"40b3f3a5",33550:"a2ced858",33620:"6de600a6",33657:"de7ce0d9",33673:"e5970534",33833:"6caeb7fe",33986:"1413ddda",34026:"f06e7b75",34177:"52f50aaf",34296:"124e7d46",34334:"ea4b73b6",34428:"fa26d017",34454:"15bf0260",34541:"1ac8272d",34596:"aa0d03c6",34654:"c0e5b22c",34663:"dd08b676",34735:"212b5690",34736:"12cfda90",34746:"07422b8c",34756:"d986569e",35033:"c56b385a",35150:"1c0b26bc",35153:"ae2195e0",35191:"cd5409a7",35491:"3f050504",35637:"21944ac9",35741:"92f028ed",35761:"e761761c",35903:"e671ecfb",36097:"456b18bc",36175:"35cc0fcd",36208:"18549e98",36425:"c17a430d",36431:"9b56f2c9",36433:"c0dc84f8",36531:"2a21f987",36537:"66526812",36611:"a18ac7cd",36812:"c9185dbc",36849:"3c2b7a36",36883:"45a8f67d",36913:"242b8d1d",36917:"faa4029c",37098:"64ff53fe",37200:"532eddeb",37258:"5247f177",37309:"7867d803",37383:"90433446",37534:"0263a9d8",37634:"79939582",37702:"53ab2698",37708:"ed1e497e",37733:"89f61296",37742:"f451ee7f",37784:"d0cca6f0",37874:"30593c76",38009:"e87f9614",38193:"c48eff13",38330:"912cac72",38391:"759e6d25",38395:"b04db539",38413:"d11c5d82",38434:"ab49343e",38457:"aecbed3b",38550:"48180ece",38636:"74d381d5",38708:"3a856ca1",38737:"bd445969",38743:"0a5e8d28",38897:"8c6a05ec",38904:"e80f9c05",39250:"9f172014",39516:"0f00b513",39552:"0078dbec",39677:"ff7f7043",39699:"b5145080",39750:"ac65bac1",40030:"384b6617",40132:"aed83937",40227:"3639695b",40337:"dc6499ef",40356:"c7e2e3b0",40655:"6a702a3e",40744:"829c4a08",40753:"84f0d5b4",40805:"f8be0529",40850:"6d7aa71a",40860:"14ae49f7",40873:"b8f2027a",41002:"51c407b4",41067:"c64fbddc",41219:"f4fef6c7",41392:"1ceb758d",41431:"bb1359aa",41742:"d2277319",41772:"2479b691",41830:"7f1be2da",41833:"d10e6edc",41869:"88207123",41903:"0fc70254",41974:"ec08512a",42100:"3a165f9f",42316:"a3910fb5",42350:"27884f99",42537:"1edbd8df",42653:"871e4b05",42743:"b5ad4633",42760:"5bf9dc54",42784:"1266c809",42799:"80107821",42820:"ff33a905",42856:"444d0845",42857:"b2aa480a",42989:"e2f2db65",43117:"f66a122b",43151:"27409706",43209:"504ec2df",43260:"f62e7cb5",43269:"21d75435",43270:"73975807",43271:"1eb23122",43332:"569a3616",43366:"e7edc475",43467:"5021852e",43607:"6034ac44",43816:"261d5fd4",43963:"fdd4431f",43966:"27d3c76c",44222:"03588a30",44225:"ee92e728",44457:"7a5b18f3",44474:"d9d2cbf1",44491:"1a34e69f",44555:"52fb2bd6",44611:"67edc1e7",44663:"d9477daf",44693:"966e19bd",44725:"0466c4d7",44955:"0def9989",45006:"96c94a5a",45101:"2a3c872f",45108:"fe59faab",45142:"4e37f83b",45169:"de031ae0",45221:"f466bbe6",45381:"0b9b2f7b",45413:"5cc76871",45417:"069921dc",45422:"eaf2a302",45555:"e1f933b5",45613:"6c7431d8",45725:"51899891",45976:"c71b92ed",46192:"17d125a0",46515:"74120125",46644:"e2c8de9f",46730:"219a13ac",46743:"c7b7f7b0",46752:"a9b929ff",46762:"a9a6e797",46857:"0f3d6737",46922:"7c6ad019",46979:"3876c50d",46984:"a4ee4544",47081:"e600514a",47161:"b28c2f9d",47162:"d589d3a7",47183:"4006d464",47478:"98a9d113",47511:"3169280c",47547:"12e3789f",47561:"80425d19",47631:"2c5be4eb",47672:"432b54cb",47674:"e1178654",47805:"93c52216",47833:"21e977bf",47849:"9c807b97",47862:"e565549d",47934:"acf7412b",48060:"0e5b1614",48068:"fab6d391",48213:"9eb3b065",48289:"40488fee",48351:"e5c2618d",48355:"fbd6426a",48461:"496e6921",48496:"32c0e07f",48617:"399a7c13",48725:"b824bc5f",48754:"15d1b497",48771:"fc770245",48942:"d1da5adf",49027:"6f040d42",49028:"09482661",49112:"7397dfd6",49119:"c7f6e498",49153:"5245b6ee",49156:"7fd337d2",49353:"21f9d022",49681:"bf2d01cd",49688:"de923e65",49870:"984cad2e",49872:"3f0450cc",49900:"a0272590",50114:"ed230530",50153:"8a625965",50177:"a463b0f9",50207:"d217fcbe",50318:"7df78dc1",50381:"01629d75",50503:"657944b3",50506:"dbbb077d",50558:"f2d214ec",50657:"8282b4fa",50675:"7972cece",50677:"20f200e1",50948:"380fecf8",51019:"5eebd93d",51029:"812a926f",51097:"d568ae1e",51136:"a28030f8",51409:"4a7dd70a",51410:"9c8d9de7",51443:"7e4b5909",51484:"49462d91",51529:"8b8c449a",51565:"02d9cd64",51587:"14a6764b",51599:"beab3968",51869:"f82e4539",51921:"b6075528",51965:"f6efba93",51976:"e2e05a0b",52079:"debfcdd8",52123:"cb87c0da",52188:"a8df8be4",52231:"6bee34e6",52239:"695dc145",52242:"84f114cd",52314:"00d28359",52428:"1cb07aec",52480:"4e60a6b8",52508:"c43bcb58",52675:"f0f73c23",52685:"c3e299d4",52696:"eb00bee8",52746:"c0f3a1e1",52764:"5b27f948",52801:"d97e8ff5",53294:"c67f263c",53769:"806af469",53776:"066acf59",53833:"9c8726e9",53839:"04b30511",53926:"d434dab0",54187:"2d46d1be",54263:"aa15e9b6",54289:"499751be",54355:"dc8ae3e6",54358:"cb89c0b0",54487:"fa09d98c",54544:"2d7dc328",54551:"5a8dd044",54648:"3ebf75d0",54653:"a306c7cc",54660:"4d3ea151",54772:"8b953e29",54857:"60158128",54898:"3ec47db2",54977:"4470927c",55085:"fbdfd47a",55104:"f4a8d251",55321:"8928903c",55408:"94b85d58",55555:"3ceba367",55598:"d8399510",55610:"fa4d2b81",55757:"fddbdb1b",55770:"941d83e7",55776:"4d6bbc69",55831:"228732e2",55840:"d3e79596",55845:"a9426322",55851:"eb31c816",55907:"cff158cf",55940:"3391b670",55977:"c0c252da",56136:"4997d94f",56200:"5e6b0d00",56205:"b358fc39",56217:"d3d19f51",56238:"f06e9ffc",56531:"9af6974b",56749:"3302a6f3",56871:"bc0f58dc",56874:"f437947b",56876:"c421cead",56918:"616d12ed",57166:"72feaf7b",57171:"17a1d54c",57246:"863b9fb4",57256:"70a09d1e",57338:"3d4bf2bd",57412:"b75f7b1c",57506:"98cf1a5f",57526:"03ba2def",57559:"201c43eb",57646:"181298bd",57748:"3551b602",57779:"28f93af9",57793:"5fa42b25",57890:"ecb16b68",57953:"2422c243",57965:"f415ef48",58053:"72927799",58202:"0d130fff",58270:"8c5009e2",58540:"f2abfe5b",58662:"ecd45472",58860:"9473047a",58867:"7ea23e33",58941:"4e591fcf",58959:"19502856",58967:"6826b540",59080:"1a460f42",59104:"77b8d4dd",59174:"21284f6f",59359:"3de9f572",59373:"e4b62490",59457:"87c82632",59694:"5766b5de",59831:"eb784468",59868:"2ee6a2d5",59925:"7c98b1f4",60155:"4b66d153",60165:"922b75ce",60275:"f44c9e05",60486:"51725525",60533:"3743955b",60593:"f22b2eb2",60757:"9be4d7d4",60849:"17961e1c",60862:"a25c917a",60905:"0aee8de5",61184:"4dc92296",61215:"5117dde5",61228:"f77e7069",61242:"5fe1b138",61251:"52372a98",61295:"ea2401a8",61333:"0cef2a3a",61389:"186d0490",61465:"a5a5bf55",61470:"6f77a78e",61497:"c595ffed",61681:"fb6539c1",61719:"e66c9d98",61794:"a090aac6",62030:"4070292b",62189:"dfe579f0",62276:"905ac3d3",62289:"647da62a",62384:"1141ea08",62489:"edf14699",62520:"7e36e062",62524:"f42b04e0",62608:"d1268a69",62888:"db9c9d9c",63093:"5b84cd36",63310:"8e54e8e7",63320:"583f9b00",63554:"d14243c6",63569:"980cffe6",63636:"b381c227",63671:"e1cfd688",63707:"882910b1",63716:"0cef0e21",63758:"d9b1f215",63791:"89ef02b1",63883:"5bf10cd6",63906:"0d1d8293",63953:"13aeb527",64044:"41a026b3",64130:"9f9f17ce",64158:"165d4317",64348:"aaacf44e",64415:"f18723a5",64475:"1ee31240",64517:"777346bd",64711:"c04d9b23",64733:"a98d3c98",64792:"5e7cdc20",64805:"4e778939",65111:"5e10776b",65279:"02ba2fd1",65345:"b39ed1dc",65592:"4c1fabbc",65598:"f3bc9628",65608:"0e43428f",65643:"61f865de",65732:"9b245343",65767:"dc76d1e8",65768:"25256696",65789:"24fa53ab",65822:"ec7017b8",65909:"5c97c651",66147:"5da65b2e",66181:"1f123095",66197:"74e1a3cc",66207:"af725113",66280:"9da27c7c",66373:"5be17b65",66418:"4b2197b8",66464:"5c0fad06",66575:"54567ab8",66598:"a775dfef",66626:"cfcf8c0e",67198:"8a62b79e",67431:"11943549",67453:"b6678181",67570:"c23eff0d",67751:"67399e1f",67784:"89fb135c",67796:"a004d986",67964:"883b440b",67986:"a1237ed4",68346:"f8e2f315",68453:"2220f4ce",68498:"0f1573e7",68677:"3751e155",68725:"0ee9058c",68750:"83df63b5",68862:"2f528031",68892:"24711014",69078:"3db0f83e",69360:"9d9f8394",69466:"1a0d3e73",69550:"983c3078",69595:"c1aa0c2f",69601:"0568624c",69603:"1c8d7345",69775:"6dbebcad",69872:"41a14838",69890:"f1f0bb48",69958:"5778bf09",69966:"833be8f7",70113:"11d71a1a",70124:"25050c59",70178:"d0d21d6b",70195:"a3d1f23a",70210:"38dc5db3",70231:"e46687b9",70258:"b1836b3f",70269:"5c672707",70520:"2a28c099",70602:"9f460c0f",70700:"23c64341",70747:"fbab1324",70804:"57a293f1",70807:"e5a2f024",70981:"8a8ac7df",71090:"79021e97",71125:"b788ce2c",71392:"1752e6fc",71416:"4d6440cb",71598:"d6797715",71651:"b5d7eab2",72014:"b3ad459e",72071:"389e6565",72103:"73f20b10",72209:"73e43e7a",72290:"0418a177",72301:"ce99103c",72406:"1acdf7ef",72475:"ff0800af",72514:"ae74935f",72523:"669a2232",72846:"12228ce8",72884:"ac285d4b",72948:"e7a1ff37",72949:"19d517d3",73021:"21b3bf6b",73034:"da524951",73038:"17809026",73050:"036e814b",73051:"f84ec093",73066:"fc1495c4",73094:"91f31bf1",73134:"b1ceea70",73254:"bced4641",73272:"d706d118",73282:"a1d3d12b",73292:"83e73561",73299:"77fd0f9f",73318:"3435c6d5",73630:"e84cabd6",73679:"e4815a9d",73706:"78d162a3",73714:"f12a9c75",73733:"e34c6ba4",73794:"aaf2ebbf",73804:"49059727",73813:"99efa9b2",73882:"f3f9afb2",73919:"c3f03a9c",73920:"122b796c",74085:"a792cae3",74111:"d058da0d",74162:"4f459a7e",74188:"905f92f4",74291:"bdd2db00",74352:"258c4920",74438:"d1f46e88",74812:"230c9e6f",74867:"9d2e93b0",74877:"9f56c61f",75025:"83c1f296",75114:"2170c9a1",75190:"bf643b2f",75452:"3181ff19",75545:"442e8a3d",75658:"766f5345",75799:"266e07ad",75963:"dca72a2a",76297:"a4277995",76477:"94715af4",76492:"a08daa90",76709:"6116bf24",76724:"f597afa9",76751:"07d09572",76902:"91ff2ab8",76921:"8bae5537",76964:"bb2c716e",77103:"18e435b6",77337:"6b2b0f3f",77378:"e5ecc38a",77394:"85a62993",77525:"9c79c61e",77534:"55710cb8",77605:"d2ae1f82",77714:"b497f2e2",77813:"686c6da9",77982:"43a61436",78055:"b595542d",78140:"a44d65e1",78404:"cb3bd380",78442:"0743c229",78477:"e2a73b5b",78499:"6b5a695e",78545:"f20bd9cf",78595:"36c182da",78729:"5c84170e",78770:"2f6bbf60",78784:"d2095685",78909:"8872cb84",79140:"6ae101cf",79187:"e926511c",79338:"f64b12af",79457:"2bff2efc",79458:"d503b0b0",79502:"7aafa071",79618:"8ea4be35",79683:"ba4608ed",79705:"2b28e252",79794:"70500b4b",79871:"5a626cf4",79882:"5558815a",79959:"38bbb6f7",79980:"564b139b",80053:"935f2afb",80102:"f3d52ace",80180:"f9758b2b",80258:"0b419609",80298:"0a96855c",80350:"7deaffec",80352:"c29e0dc6",80366:"43fd43b2",80382:"9f6922d6",80395:"a0f27e39",80471:"f4a489fa",80481:"233bd232",80597:"633b4268",80683:"7809eda7",80707:"d9bd109c",80742:"9ca34565",80757:"3b19df91",80781:"c813dfb6",80784:"27a0e9a6",80922:"e0c5b57a",80929:"75f97e01",80957:"1e04755c",81026:"2de82f74",81113:"dc993438",81131:"88fede05",81147:"5b356f0c",81206:"bd1f4d4d",81324:"091dfa99",81475:"32b9dfa4",81500:"90cb80f4",81519:"51aa6ffb",81623:"e685fe7b",81627:"7f615251",81674:"cc1de87f",81720:"72e3ea67",82009:"a73e121d",82048:"3f5735fe",82161:"578e646f",82229:"31246fe3",82247:"c903ba62",82283:"b7c24ea9",82384:"b6ad761b",82385:"112d7f90",82500:"e47c2663",82724:"31d59ae5",82934:"eb7b1076",83056:"23b1efbb",83058:"3073ccb9",83075:"469439b3",83081:"6a63eeda",83082:"7a3fef43",83100:"68cd29cc",83102:"7a399052",83210:"a8803ad0",83231:"b28b315b",83352:"9b061d60",83353:"c8a4fc71",83425:"2121efdb",83454:"701689a3",83470:"bebb551a",83488:"a5aa0181",83544:"5b9d5773",83651:"0e1330ab",83878:"7ba381c4",83889:"34d3812a",83969:"cfb30de5",83995:"4ee76210",84002:"63dcc201",84024:"eed3d70f",84093:"f52c5b6c",84146:"8ae68021",84170:"235b22f9",84305:"37c8d80d",84501:"b9300de8",84549:"f4b387c6",84585:"5df3ccad",84668:"801615aa",84892:"72f20b9a",84936:"c86089cf",84994:"15bd7fb2",85098:"a732a816",85158:"36054b2a",85165:"fc816072",85498:"d35253c3",85587:"636f78d4",85657:"8fc50042",85928:"6b86a004",86006:"a52caeea",86007:"f59cc2df",86056:"df228eb7",86062:"1fe53564",86079:"e16f3e23",86080:"92261483",86169:"62180679",86229:"740cfbc5",86459:"349c6fe8",86479:"f114c040",86505:"4f44017e",86593:"76708471",86717:"02c13856",86730:"05a30404",86740:"16715f67",86746:"4c21325e",86751:"c8740552",86883:"6705557d",86955:"09139d96",87069:"98dedf47",87293:"41b84bc1",87302:"bbc5be04",87376:"14ed99a3",87439:"e46f8a72",87458:"609de602",87496:"8250ab46",87554:"1a04ee3b",87606:"cddfa015",87964:"7925dbd8",88055:"eb00ac44",88085:"cd3e9f7c",88092:"f4695122",88127:"2c9009d3",88167:"65039b67",88205:"c6c759c1",88209:"2e94af40",88262:"0d014f06",88438:"d49aaf69",88445:"2f54a133",88469:"60c90a58",88661:"510af3ef",88768:"00a8cf8f",88812:"271688ec",88823:"dd93d2e4",88990:"804c7efd",89067:"d8eecd3a",89118:"b3428692",89147:"3e7201c4",89178:"c157ad58",89221:"8b2e9ec2",89244:"de7959df",89284:"8bb9a2f0",89357:"4708e904",89383:"38c58766",89473:"214808df",89474:"3c095580",89573:"0775542f",89671:"dc482cb1",89730:"11740645",89782:"b16ab873",89839:"6c1d1c3e",89938:"412fbf9f",89961:"2da1cf89",90129:"af3a8c26",90134:"81e479c0",90143:"fe1522c6",90216:"83d651a6",90269:"c9a0d8ae",90475:"97ae6f54",90674:"85028062",90802:"8acdc9b1",91077:"cdac035e",91091:"6b26ffce",91215:"df8bf24c",91360:"b0ff3ac3",91483:"8b2041b0",91565:"f4b833b3",91692:"18c961f6",91702:"9afefd1f",91743:"8734afb6",91789:"b18e31b7",91859:"748bf8b3",91869:"dd080071",91951:"fb9fcb5b",92099:"9cd05c6e",92289:"76e8764f",92296:"771fc4e7",92412:"be3f031f",92485:"1ac14023",92528:"96947e44",92627:"edecde5e",92657:"e998e5db",92778:"4f6dcf60",92993:"37ac39cf",93262:"168ac9d4",93369:"eb7fdb35",93420:"870fdbd7",93441:"ed765822",93526:"8b600e92",93627:"edc9c83a",93784:"e028d6df",93853:"f1c8cdb3",93857:"ed232bb1",93865:"c9869c67",93889:"31ca016c",93923:"eb3cc724",93927:"6304a1c8",93931:"a198644b",94124:"8a1c07a8",94205:"3c776bab",94232:"1b0c6d7c",94321:"cfa759f6",94398:"a2dfdd17",94594:"dca25a09",94727:"15524dd1",94747:"ca67bde4",94761:"e13750cb",94986:"57b790ef",95035:"6ecc7926",95129:"2d2a049a",95163:"7d2af5f7",95215:"6e1cd7e3",95406:"49a6cb80",95669:"7afb09d3",95787:"160c20b4",95836:"89188be0",95924:"060bb38f",95932:"392750e5",95986:"92da714b",96034:"2e39e31e",96203:"67e456bd",96363:"000b0b3b",96391:"535687f0",96403:"7df29312",96440:"27082a20",96481:"89e79058",96540:"818cdfcc",96543:"dcbc72b6",96571:"aac2bc09",96684:"83bc5b60",96687:"2de98f94",96756:"96e5a9c0",96774:"1bb63d8d",96861:"886b0cec",96916:"1a412b79",96926:"5731ca57",97006:"5a7ef470",97180:"b0bf5481",97241:"553ce7ec",97310:"17aee925",97338:"f8cd448d",97457:"fe5276da",97462:"053401a3",97466:"bf1c9a15",97628:"cdda4d34",97659:"50629e36",97668:"0ceb5061",97680:"6d809921",97746:"b18e806a",97773:"90ab9f19",97795:"0ebd1ec2",97807:"20d125e4",97815:"501e3680",97920:"1a4e3797",98055:"8d2cd206",98211:"1411c025",98224:"dfc9ab0a",98253:"1468a817",98285:"387a4238",98431:"4b471a3b",98471:"a584238a",98478:"c383dea5",98488:"9a03e1d3",98535:"cadf7bf8",98566:"5e3cd947",98619:"f366db13",98647:"3acaaf8b",98650:"ee30f3a5",98685:"fd02bb74",98764:"c8767106",98853:"b7192f86",98905:"68132c44",98906:"5c9858b7",98915:"4b1580d8",99200:"4f286fb2",99296:"1e28d2c3",99344:"2615ed93",99354:"fc542f76",99444:"4eb132b7",99469:"2f86cf9b",99523:"d0123614",99544:"8d0b1d0b",99557:"bbcb5258",99622:"a920fb26",99635:"f5172bcc",99669:"44bcd317",99677:"a8412436",99802:"6732b456",99816:"ff304de5",99871:"47d2b372",99917:"100fe9a5",99969:"38080670",99988:"7a6a8bb0"}[e]||e)+"."+{92:"535a28d6",151:"a5cdcb49",218:"8684d373",426:"2ceaf3cf",470:"6421cc01",543:"4a279379",560:"be539269",692:"46bbb018",803:"353b7783",858:"a68a89e6",876:"8363b35b",1014:"a57b46d7",1074:"68903e7a",1188:"a250d3a2",1233:"5be96823",1272:"d93b4c7c",1307:"391f5aac",1441:"db3fd9e1",1484:"4f65d1f2",1665:"e68084fb",1847:"623dba51",1995:"ca50bf4d",2073:"d4a48703",2207:"480eeb69",2309:"31206cfa",2334:"5b2b55d9",2371:"8299e86b",2463:"f3c47d3f",2476:"dfb82135",2535:"566197c7",2746:"9e6c7afa",2786:"fa13404e",3181:"b18adae0",3254:"36ab8c80",3260:"42cf43fe",3299:"aa0ea155",3445:"5f4bc9aa",3776:"0e64b3fa",3957:"8d0d1248",4180:"a408cd6e",4215:"a862d797",4267:"6f102b8f",4311:"4da50505",4397:"c7f53b9c",4493:"7f3d26b6",4494:"4a9bf2e4",4502:"dce80dd8",4583:"078ddbf2",4589:"7a41fa7e",4803:"9cd5d669",4947:"324c5451",4972:"69f6cd4c",4983:"7f881d5a",5008:"eaf66e77",5093:"e7a5d816",5099:"c48aeccc",5105:"524b9a58",5118:"4b3c58b0",5230:"ef60d17f",5280:"2a82facd",5324:"98b4bb3a",5370:"00b8a8a0",5418:"b9620785",5706:"3e3b7fe3",5839:"d9cb4e29",5916:"7849d2c4",6054:"938e62ba",6061:"1d2c2d4d",6162:"e47c65b3",6379:"ca349df6",6495:"7621047f",6508:"2215a1cb",6592:"6e3f4a98",6617:"f7487a3b",6694:"9adc7017",6763:"d19e12c3",6810:"4e98c634",7070:"6cda2c58",7297:"7f398627",7366:"5fba47be",7450:"94e1a824",7573:"bec8975e",7587:"973f6cae",7654:"94a22298",7658:"c41d1243",7670:"cd93850d",7703:"33ce4beb",7911:"7b32e6ef",8038:"2953f7ac",8092:"20914538",8145:"f20dcb50",8226:"54bfa0a5",8281:"a2f34fca",8282:"2729ef25",8362:"0347c464",8392:"0151debc",8473:"f2f90f11",8491:"7c4dfb72",8562:"2a0d4ff7",8631:"3b7d9c8a",8644:"f3f2b585",8701:"b0fb3909",8769:"d8574234",8799:"14eaddb8",8899:"6e5fca44",8901:"1d811244",8924:"27c84b9c",8952:"e2206404",9017:"6474812d",9136:"0f06364a",9324:"2c99304b",9391:"80511dff",9575:"c07e693c",9595:"2a21f145",9613:"df557afd",9644:"176aa807",9712:"0e404c54",9806:"c9f442fb",9877:"a1a8fd95",9899:"0e843ea6",9909:"5692688e",9981:"25d5face",10003:"6e423100",10025:"403d1fec",10071:"87d20cc4",10146:"bbb17c3a",10195:"cfaf39fc",10246:"acbfa7c1",10325:"bd1f5b9d",10355:"12a31bcb",10438:"da5473e6",10557:"016137d1",10571:"4ec1f7bc",10632:"594222ea",10814:"8b907702",10865:"ecea7671",10889:"a6f345ff",10923:"feece7ea",11018:"ead209d1",11123:"554e5f3b",11139:"723813c4",11212:"2caf5eb6",11303:"4d3b04e6",11367:"fb0e1f3d",11405:"206041ed",11532:"d23e40ec",11569:"a94285d0",11785:"ff4292fd",11810:"fe5456dc",11835:"dcff2f39",11842:"c8fbe67f",11955:"8391db38",11986:"ea7c271c",12048:"53ee497c",12231:"7f8bf12a",12428:"c36a3e82",12463:"7ec08174",12495:"984bebad",12547:"2f76a18c",12584:"a7435ad7",12616:"70eac114",12748:"31995f75",12752:"fd4f5400",12821:"93459e3c",13e3:"4a8d517c",13073:"74574142",13085:"dde0024e",13097:"3ea41088",13134:"2ecd4487",13276:"5d87571e",13290:"ebf2cf40",13297:"d00ef79e",13438:"d2700d98",13453:"0c4b1f22",13546:"e600be81",13579:"2b3bdeb8",13715:"71205e7b",13838:"d4377bea",14075:"739f29aa",14114:"8d627851",14166:"aed7e56a",14374:"cc93a17b",14418:"edeb4322",14512:"1968686f",14515:"c77c96e2",14525:"580e9409",14754:"eab494c5",14755:"3400b8c1",14950:"1248d382",15090:"7812b21e",15149:"d4728d15",15403:"fd08573a",15474:"e0956e13",15619:"794c42f9",15640:"a3b9c30e",15708:"243ce5fa",15872:"58fbb54b",16008:"b4933583",16137:"0124a212",16183:"bc883d9f",16290:"df2f0239",16692:"57f42815",16861:"6233fdc8",16914:"7df5ffea",16990:"e46168dc",17088:"8561d378",17287:"174fc89a",17351:"56818b3d",17397:"30256042",17459:"c2828245",17538:"9749b315",17659:"b4aff8d4",17670:"c57740ab",17726:"a866eab3",17870:"38015208",18004:"ec67437c",18064:"7cb556dc",18104:"4300cd1c",18165:"bc1dc5f7",18291:"ae9c7514",18329:"b3065740",18368:"fc22ff32",18428:"5e6591a4",18445:"298e1915",18617:"1cfd3dfc",18820:"56c33705",18846:"c5b49faa",18856:"4ca9b82d",18894:"c2a7125b",18911:"ddbe1329",18914:"67d73ab4",18953:"7e83bf96",19098:"abbf890e",19123:"3a916cb3",19179:"a6089e1c",19214:"1a36a76f",19218:"c20a90d0",19465:"6d755f90",19489:"e9ac53df",19510:"b1004ab7",19614:"8e2e4952",19776:"2a91859d",19808:"36865124",19853:"6b053351",20080:"7247eff1",20175:"546fe057",20334:"82c2598e",20357:"d6cab0b0",20425:"17c43b8e",20689:"70429130",20770:"ed26f7e6",20787:"37d127d7",20988:"f7584e30",21156:"b857021c",21167:"e960c341",21187:"732014d1",21210:"6cffc295",21245:"ec97f924",21419:"e9d9e0a7",21538:"d061c47f",21705:"b67f970f",21739:"b0f75223",21911:"bfec9913",21931:"3214fba7",21958:"9228f8de",21981:"3c8f6b79",22007:"aa946fa3",22145:"780339a2",22245:"ef785d62",22302:"c19b31bc",22376:"a7bf3256",22460:"2f2a47a3",22483:"903ef67f",22520:"e52c9f94",22546:"832b4a3d",22675:"66bbe4de",22856:"fad9e05f",22894:"ce970b4b",22895:"d42022d3",23044:"6e0dc0db",23212:"844c5eaa",23345:"84af3ad4",23402:"8a4f10c1",23561:"da83b63b",23791:"f57b6ec7",23798:"1ebcd8dc",23840:"a54429c4",24038:"1f034733",24085:"c2c9d81c",24242:"2ff474be",24273:"0c95cf4e",24404:"5ecf5124",24521:"65b4ecfd",24681:"cebb1d3c",24741:"e3a8a7fe",24836:"dd819f46",24954:"539a5724",25215:"68f28a48",25226:"d9e19ab4",25279:"abf76f9f",25350:"4071d62c",25438:"38069028",25567:"ef9c0e90",25589:"ce4d8688",25863:"d9768176",25875:"e823fa4c",25877:"9d5ab0a7",25991:"cc00472c",26044:"5acb0300",26075:"2f1f7395",26250:"6d1612a5",26283:"6fc8539f",26353:"db8ed48d",26446:"9076570d",26725:"943e4570",26743:"60f90701",26875:"dcccff2b",26966:"94f5517c",26976:"46e6ad3f",26989:"cbefdaa4",27061:"6e07c150",27063:"f30e6bd9",27301:"5fae3af6",27349:"32a77190",27392:"70bba2a9",27468:"ac8975a9",27557:"a6669189",27565:"53041ee8",27656:"4046c415",27717:"40f5b827",27740:"34084d1e",27837:"d0b73bda",27918:"76f426ee",27987:"cf6b0594",28320:"568d9f6c",28337:"29610372",28491:"6e54b73c",28605:"a9b29127",28671:"1fe8c92e",28768:"b9bc9e2c",28823:"03bcdb86",28905:"9568f6b4",28934:"14414934",29143:"561b9e94",29294:"fd7ff693",29354:"d92106ae",29389:"1b18537e",29449:"93d59452",29514:"0d33649c",29617:"93372a7a",29679:"daf6c534",29705:"ead3527e",29738:"dd42caa4",29795:"78fb3f02",29797:"0d381054",29890:"c65a6b1b",29956:"62f45366",30192:"635c6f02",30225:"b332a40f",30285:"9fa253fa",30337:"ef460f86",30362:"157e6951",30382:"e91ea60c",30394:"d4cf9e4e",30538:"42fc5c45",30575:"ca729dc8",30585:"f16344bb",30654:"fd9ae86e",30685:"0b9e5cc5",30836:"16d4f8aa",30949:"f0268686",30951:"8d91020f",31032:"bbd394b4",31060:"2681286e",31076:"c4b72acf",31155:"7c8a6a28",31190:"ae8c4b48",31377:"5a585776",31510:"c4892a95",31558:"f2ca37bc",31732:"2d0959ee",31749:"d17a4cc6",31863:"2a49bfd1",31869:"9e3f3415",32163:"09a72998",32165:"5ca3d3a7",32266:"2568e26e",32356:"4a1a1537",32411:"adb121a0",32513:"0d0f9447",32527:"03e84f4e",32666:"046f323e",32691:"b8c35159",32697:"4021ba61",32714:"68ec6ddf",32959:"edadbe64",32991:"4142b884",33016:"d6a5bbb3",33017:"2a23a2e6",33036:"5ef1c102",33083:"725f4e22",33084:"5d3f8f53",33183:"21e25b89",33188:"7e136810",33296:"247b97f1",33306:"48360443",33458:"b1b01f50",33472:"79679fb0",33550:"bf194218",33620:"e942a8b7",33657:"6bf6073f",33673:"efdc9ff4",33833:"b4d6ee97",33986:"320402ff",34026:"1ef57b57",34177:"a37ab43b",34296:"0fd3340d",34334:"8bb020a5",34428:"ad7812f2",34454:"c4b4784d",34541:"e66106e5",34596:"cec5a879",34654:"6564127e",34663:"bcc2613d",34735:"a8e4e044",34736:"e84b46ba",34746:"38e19e8c",34756:"578b1313",35033:"f1b866f6",35150:"a7142914",35153:"0a1ed7af",35191:"b161842d",35491:"72d70e80",35637:"b9b4245d",35741:"4845c34a",35761:"a68f0e6b",35903:"63174413",36097:"ef799774",36175:"086fe722",36208:"d04ed314",36425:"1b8b18c0",36431:"9afd6801",36433:"4e70ffe0",36531:"25c88b11",36537:"f3c2f247",36611:"def7f39f",36812:"46d06d79",36849:"2f481f98",36883:"794fb5e0",36913:"0a2d05c7",36917:"bd26c62b",37098:"78cf5676",37200:"1fb18f99",37258:"8a211351",37309:"b3b9f586",37328:"c4bb0f6e",37383:"a33c1425",37534:"3376f20a",37634:"98651280",37702:"e849dfb3",37708:"d7f35daf",37733:"e57595f5",37742:"dec2237b",37784:"89924114",37874:"b3cd3de4",38009:"5dbe9819",38193:"368c7447",38330:"a2e123c0",38391:"5ec113ec",38395:"6d71e6b8",38413:"282b976a",38434:"b9f79fc7",38457:"2a7e410e",38550:"1c2e4010",38636:"9174ae11",38708:"a0cbc6da",38737:"747f8639",38743:"f2c2f193",38897:"4cdb2bf8",38904:"0537dc54",39250:"32a3c8b7",39516:"43f891d7",39552:"a27d8811",39677:"f8a103c7",39699:"7c64ad33",39750:"3b1dda8b",40030:"322abb77",40132:"102143e1",40227:"418dc0ce",40337:"62004783",40356:"506bd240",40655:"ea5e445f",40744:"1e3f0312",40753:"1aebb11e",40805:"d34eae98",40850:"d09ed0b4",40860:"80f282b8",40873:"25d4d83e",41002:"c7033b07",41067:"39374493",41219:"adac7d00",41392:"60cf29c2",41431:"c35a90dd",41742:"52a71b3b",41772:"4023cf8c",41830:"267ef385",41833:"2dc2ed87",41869:"726db2fa",41903:"03ce8bd6",41974:"904edc50",42100:"e5051585",42316:"302fffb6",42350:"6305c1cf",42537:"e49a7a3c",42653:"443fc0d9",42743:"072bf6b3",42760:"ebf286b4",42784:"35469de2",42799:"0b6ad83a",42820:"35724c0f",42856:"d6ace09e",42857:"5479f9bd",42989:"fcb77b9c",43117:"104220c6",43151:"fd459b3b",43209:"20600400",43260:"c286e838",43269:"1d7e14cb",43270:"bf61ff9e",43271:"6237c315",43332:"907da18b",43366:"c6357540",43467:"d637f5e3",43607:"7427052d",43816:"62e63002",43963:"9c2bb48b",43966:"f0a451a5",44222:"ed8c8f2d",44225:"c0c5ebd4",44457:"5213fe0e",44474:"1a6ab166",44491:"81d5765a",44555:"e7de74eb",44611:"0756d221",44663:"9701e166",44693:"57a4dbab",44725:"3b1c899f",44955:"633f75d4",45006:"90749b11",45101:"446078ef",45108:"7c3b1c64",45142:"dba8de6a",45169:"3b377223",45221:"ffc095ef",45381:"3ce5100e",45413:"dcf75492",45417:"1235c2a4",45422:"fa8f40ee",45555:"e74ebdcc",45613:"e866a17a",45725:"316f4bb4",45976:"81d02f64",46192:"e40fb460",46515:"f427e51a",46644:"6e9288fe",46730:"62944739",46743:"3865a2c1",46752:"9acb84b9",46762:"5e3e7da3",46857:"9e9b24e4",46922:"af84397b",46945:"e7eb5108",46979:"4f57cd9f",46984:"31cffdfe",47081:"35bb408d",47161:"8533fba1",47162:"dba2b151",47183:"053650da",47478:"3ae4bf40",47511:"506ae887",47547:"abdd93ca",47561:"b659ae1f",47631:"f03351eb",47672:"a9b32ec8",47674:"3266ac12",47805:"d8eae175",47833:"257cfcef",47849:"512be15d",47862:"4f9134a7",47934:"4004d791",48060:"f4db5ca0",48068:"27b01a32",48213:"dcd81cda",48289:"9f9a7a2a",48351:"6aef791e",48355:"c2ae0bc1",48461:"e6b67439",48496:"ec6aa069",48617:"870b2ceb",48725:"dda2579c",48754:"7d4e8b39",48771:"0d4847c8",48942:"d3f12fe8",49027:"a40deea4",49028:"2b4ae1d2",49112:"3d93b1fe",49119:"f0daaf36",49153:"99976ddb",49156:"942b3701",49353:"a3640717",49681:"077fbfd0",49688:"20dd248d",49870:"3287e540",49872:"bd87aada",49900:"c462969b",50114:"1d92a548",50153:"f22d794b",50177:"8532e1a2",50207:"751fec41",50318:"ba0eb5eb",50381:"6c6319cf",50503:"177f120c",50506:"fc7f21d7",50558:"89d8d15d",50657:"d5c9cfe9",50675:"d19078f3",50677:"c8d7ec86",50948:"3a98336b",51019:"e224ed56",51029:"143d535a",51097:"4cae1b61",51136:"db24d85d",51409:"5ac8a220",51410:"eb761c22",51443:"26dc5351",51484:"7be3e4dd",51529:"1692fd90",51565:"458f1b97",51587:"76860893",51599:"52bd9663",51869:"08e8cbb4",51921:"d2bb1240",51965:"aec35871",51976:"eaf6ad5c",52079:"38cf9ae5",52123:"2daaa322",52188:"8bf27aeb",52231:"e7e834a4",52239:"b28594d8",52242:"4aa49b65",52314:"432afe50",52428:"f1a94234",52480:"a4b0af4b",52508:"fad4a7bb",52675:"45463762",52685:"ec046fe9",52696:"b9c35dd9",52746:"de4a25eb",52764:"146811b5",52801:"c3344530",53294:"9dd47473",53769:"9b655c88",53776:"069cc32a",53833:"7fd988fb",53839:"f35e971a",53926:"0631ee1d",54187:"ef2414a3",54263:"3281e3c6",54289:"6fc8e35c",54355:"5feac870",54358:"0c6bd717",54487:"d621e575",54544:"d009e8f0",54551:"eb557c4d",54648:"a0e2fb3f",54653:"47d6882f",54660:"e1cfde55",54772:"2c8915b9",54857:"54fb9573",54898:"189783c9",54977:"58b5b73a",55085:"9bce3fc6",55104:"f9eb18ea",55321:"39624bbc",55408:"c96d77bb",55555:"83b2fe87",55598:"536d6b09",55610:"ee04da1e",55757:"045af70b",55770:"b2c46f62",55776:"48de51db",55831:"79ffd63f",55840:"7e9480b1",55845:"ac2d2b14",55851:"dc8c38e4",55907:"26937c68",55940:"3289b6d9",55977:"c0c7f24b",56136:"4bd18a00",56200:"a6356951",56205:"343ea0f3",56217:"bf84a591",56238:"0a599769",56531:"d6018180",56749:"dd5e7507",56871:"a43b3012",56874:"48f2dbfb",56876:"4f2f05dd",56918:"60cd2a96",57166:"fa56ff88",57171:"85179503",57246:"4dd4bc84",57256:"7adf996f",57338:"bdfcb8c1",57412:"7c5f254e",57506:"8b3e4221",57526:"764a4adf",57559:"69433c1a",57646:"a751f782",57748:"bd31b45c",57779:"bd395a44",57793:"9038fbaf",57890:"dbacad2f",57953:"1d6bf78f",57965:"a53ed685",58053:"94bc0e0f",58202:"c5439226",58270:"e51be0c5",58540:"455c6ba4",58662:"dbed5459",58860:"cc04598c",58867:"b8348f33",58941:"44579497",58959:"5ee1c06e",58967:"18a75ff7",59080:"56d6c64f",59104:"6490e813",59174:"4a9fe322",59359:"8dc55a26",59373:"0d93c70d",59457:"454c6390",59694:"4a11c655",59831:"b19a9981",59868:"19292318",59925:"0354d339",60155:"9cd78e06",60165:"c14392bd",60275:"eade44cc",60486:"f6c23c5a",60533:"bf6eb166",60593:"54dd1bbf",60757:"b14df74b",60849:"f571c38a",60862:"4f13a3e6",60905:"02437552",61184:"97755d31",61215:"9ab007a2",61228:"e4b844af",61242:"7e230539",61251:"a7a9c0c0",61295:"1d8eb3c2",61333:"caf12e36",61389:"a9e51a54",61465:"7f185f97",61470:"e5be67a5",61497:"904867f1",61681:"e876e0c5",61719:"139b6e1b",61794:"765e5f47",62030:"33dcbe0b",62189:"f24ad146",62276:"993a2026",62289:"218ffb26",62384:"11df8246",62489:"3c1e7e02",62520:"7c1d7b69",62524:"feaaf299",62608:"e7416c38",62888:"fbe55a66",63093:"83a9c8b0",63310:"caba2c22",63320:"013dd6ba",63554:"99caa6e0",63569:"74948dfa",63636:"eee2858a",63671:"9fa8c23d",63707:"1b70b723",63716:"072f9e9d",63758:"0e59a525",63791:"4ea7d528",63883:"e39e2c04",63906:"a1741d3d",63953:"b9a41d7f",64044:"3814e78f",64130:"711381e8",64158:"0dbd08ce",64348:"7382e722",64415:"94f564c5",64475:"497cc096",64517:"61328e38",64711:"b4b09ae2",64733:"15191a41",64792:"ff8a079d",64805:"4da6ad74",65111:"103134d2",65279:"884bf7b7",65345:"220637c1",65592:"b232c00f",65598:"9592a4bb",65608:"f00f6230",65643:"f6c969c3",65732:"427ea594",65767:"e6fe5f2e",65768:"66955f4b",65789:"3a53cfa2",65822:"c78085d1",65909:"195e2749",66147:"a9d9e09b",66181:"8ec70726",66197:"fe892181",66207:"b3c87b40",66280:"6d309f48",66373:"555e9c98",66418:"a843ff29",66464:"b986bae7",66575:"9057c318",66598:"92cfd750",66626:"6fa5c6c3",67198:"6ad2aa0e",67431:"f48723d0",67453:"18b29091",67570:"984bdc34",67751:"fe72bc7d",67784:"313b1c89",67796:"69fbb5a4",67964:"8836b877",67986:"248d36ac",68346:"f7740da1",68453:"1385e606",68498:"5aba3b5b",68677:"ec8edc56",68725:"e1664891",68750:"123d9ecb",68862:"a3b00d11",68892:"b80b7c68",69078:"9d7fd0f3",69360:"8c88f5e5",69466:"b40ab867",69550:"b54a07b5",69595:"353b19b9",69601:"f1b2f91e",69603:"56fe94f5",69775:"1125ec95",69872:"3b51da84",69890:"c06bd1f8",69958:"2b82839d",69966:"4a5d3ce2",70113:"32c880bb",70124:"66a5d682",70178:"685379d4",70195:"f0a65784",70210:"a844794a",70231:"c9ab983a",70258:"4f6b7098",70269:"981c3edc",70520:"0b9eb412",70602:"23e33787",70700:"70eeadb2",70747:"5971b4cd",70804:"1c87ee5d",70807:"b11e4ce7",70981:"83aae562",71090:"816be372",71125:"b00667b9",71392:"45266cfb",71416:"79d48d12",71598:"4d302c30",71651:"407713ec",72014:"5dd924c9",72071:"26fa81c4",72103:"1d1c8a72",72209:"67c2cb59",72290:"064e7aeb",72301:"4b03f43b",72406:"99ae91f4",72475:"e5aa0f74",72514:"ec90b7c4",72523:"00fde868",72846:"e8d214c1",72884:"3fae4551",72948:"ea3df05b",72949:"fa5d2b63",73021:"7a6529ff",73034:"e12e03ab",73038:"b18c7f51",73050:"04ed1ed2",73051:"6456d8da",73066:"d4441034",73094:"12efdc8a",73134:"861af494",73254:"0b020ed2",73272:"dd2d3db9",73282:"05a01347",73292:"eeb9bff6",73299:"c5d0185e",73318:"ff685d3f",73630:"483b5851",73679:"7229536b",73706:"f176e716",73714:"b814b661",73733:"979df0eb",73794:"028f7898",73804:"80e822c1",73813:"090443b4",73882:"272cf9fe",73919:"d417c424",73920:"2ffb7780",74085:"c3e74dbb",74111:"2b58ced5",74162:"227952a1",74188:"55510695",74291:"c46e85c2",74352:"4acd3508",74438:"8ceef940",74812:"dc8f75a8",74867:"ad3a3974",74877:"524690cd",75025:"ade7ea5f",75114:"01ff82c4",75190:"e86a4357",75452:"f83636b2",75545:"352aa1d2",75658:"bbff8fc4",75799:"80523442",75963:"881d5ad2",76297:"2158f07f",76477:"620bc63a",76492:"11201b21",76709:"72c6a25e",76724:"6711a60d",76751:"8167481a",76780:"3ad3fec4",76902:"479b5db9",76921:"88193994",76964:"2745d586",77103:"668b2761",77337:"55fc6cbc",77378:"bad7db08",77394:"9de0272b",77525:"ad14f638",77534:"ba2be641",77605:"fb26e74a",77714:"c8f65954",77813:"7a990028",77982:"e093a8b2",78055:"492b8f78",78140:"304f303f",78404:"13643c62",78442:"bca48136",78477:"f8b7b85f",78499:"22d5252a",78545:"86c5e66b",78595:"9e8742ea",78729:"7d77d735",78770:"c9d5b426",78784:"ca008628",78909:"b44f3bf7",79140:"2e615b5c",79187:"98537e0b",79338:"f550b3eb",79457:"c499c4c5",79458:"86114dfe",79502:"0134b282",79618:"578b9cbe",79683:"353feec5",79705:"11fa6ce8",79794:"3a579921",79871:"184aea33",79882:"516732ec",79959:"b76b6fe1",79980:"87164a66",80053:"dd8f2869",80102:"1103e64a",80180:"14e3fcac",80258:"184d68cb",80298:"67f37377",80350:"97d7f764",80352:"4d999fc3",80366:"a2467da1",80382:"78b8586f",80395:"b53911fc",80471:"ed0d866e",80481:"b29eaf9b",80597:"7149f1cf",80683:"4bd76d03",80707:"04cc300f",80742:"85bfd7e4",80757:"322d5d5e",80781:"bf6cf1f4",80784:"ded9a31f",80922:"db0b32bd",80929:"0e772bad",80957:"45e08b2a",81026:"d5d6d18c",81113:"15e596f0",81131:"44fb2c77",81147:"cf560198",81206:"db753b4e",81324:"eb84fbd7",81475:"1259d877",81500:"eb036a5a",81519:"7e74f32d",81623:"7acf5b82",81627:"38ad2086",81674:"4dd36fdb",81720:"3b4191a5",82009:"30c2c329",82048:"bf6967df",82161:"fc331579",82229:"e278917d",82247:"090cd1ea",82283:"2809c695",82384:"0f9383f3",82385:"19bb88a1",82500:"e91a3564",82724:"a553ba3c",82934:"fa7b4970",83056:"2cb69935",83058:"515c7e28",83075:"59c7cc51",83081:"dc442dde",83082:"997abd47",83100:"cde6b887",83102:"556f7467",83210:"fda69c0b",83231:"015871c9",83352:"4b25b461",83353:"d36eeeaf",83425:"fc5a37cd",83454:"90812554",83470:"77b90cea",83488:"1d0d1314",83544:"1498db6a",83651:"8d0d198d",83878:"5dadd351",83889:"a2ff1194",83969:"527a016e",83995:"83d122b0",84002:"bde9730e",84024:"c166a7a6",84093:"45833371",84146:"0844a241",84170:"f71408bd",84305:"c2280e54",84501:"9dacf513",84549:"1873b686",84585:"02a62b44",84668:"5dd7103c",84892:"729b3e0a",84936:"e62ff242",84994:"f78108ef",85098:"fcc1afb6",85158:"6117cf06",85165:"097bbf73",85498:"dbab45ab",85587:"39573440",85657:"96260064",85928:"a4c8af40",86006:"d517592c",86007:"98c7cb48",86056:"15c0b0b7",86062:"b735e4df",86079:"6a8b65ac",86080:"42b02c56",86169:"9eb9f836",86229:"30eb5ef3",86459:"45310015",86479:"65c1c405",86505:"4b7beb8d",86593:"9afea15c",86717:"3313775c",86730:"65ff6c28",86740:"26b96f23",86746:"f506bb3e",86751:"84924788",86883:"ff8236f3",86955:"f414a927",87069:"dc7a7cc3",87293:"310acc9f",87302:"e568bce3",87376:"341e57c3",87439:"46967fe7",87458:"df47c75f",87496:"2b50670f",87554:"6852a3bd",87606:"b9e932e3",87964:"5eafbaca",88055:"5c741d7a",88085:"61cf34c2",88092:"f3cf5544",88127:"ef5b8e19",88167:"c9b52319",88205:"68800bd1",88209:"64a0243f",88262:"667b764c",88438:"6d7c24ac",88445:"18aa0d43",88469:"e27db3d4",88661:"728d7340",88768:"6a651be2",88812:"948c4ba0",88823:"ee8cfa33",88990:"d622361d",89067:"09dedfba",89118:"149726e1",89147:"82bec8ff",89178:"8feec8c8",89221:"a641c2d9",89244:"d265b281",89284:"c5ed60b5",89357:"5491b86b",89383:"910fbf56",89473:"b61c2c16",89474:"0721ea92",89573:"367a5b08",89671:"4dd782b9",89730:"88be35f2",89782:"403eb6f6",89839:"51eac1ee",89938:"48e66efa",89961:"c00e806c",90129:"d553f69c",90134:"c040e7a4",90143:"0d46b9dc",90216:"08c7d6c2",90269:"b91646a1",90475:"85a75f3d",90674:"6df9699f",90802:"9569477c",91077:"dbe3e93f",91091:"d7aad258",91215:"c01b40cf",91360:"167bbbc9",91483:"414d6b9e",91565:"3e07e201",91692:"a778d712",91702:"910a0768",91743:"acd102a6",91789:"1364be6d",91859:"71d3c754",91869:"9e723314",91951:"158bdeb4",92099:"322ba068",92289:"e54ae662",92296:"0e6bfb76",92412:"a94d8851",92485:"76112eda",92528:"b21994ad",92627:"d1ec4ff0",92657:"8ccc6ea8",92778:"365f375b",92993:"4613d09b",93262:"4cdf0a8b",93369:"16114c8e",93420:"85064337",93441:"20bd2b14",93526:"28015b24",93627:"8d424660",93784:"a1f52e6c",93853:"59e45c82",93857:"3d1aacab",93865:"32c9c0b1",93889:"459a2685",93923:"7b384e9c",93927:"f55abe09",93931:"abfca5a6",94124:"b3b51880",94205:"aab9e8ff",94232:"0ed56806",94321:"1ba035df",94398:"13a0fec6",94594:"c5b629f5",94727:"78b137c8",94747:"7c14d22f",94761:"b7cc3e3c",94986:"8085cd9b",95035:"4e9e1512",95129:"1f8e282d",95163:"d2b4ad44",95215:"738c08fd",95406:"57ab0c5a",95669:"7d86bcd8",95787:"8a654fac",95836:"4e9e6cca",95924:"66594729",95932:"4ed01ebc",95986:"dafbb84b",96034:"6226761c",96203:"20494bde",96363:"e4a6eb7e",96391:"ffdf2a45",96403:"3a5c5da1",96440:"b3971c0f",96481:"92fae2ec",96540:"82fbf8e3",96543:"1638716b",96571:"8d91e091",96684:"505c7118",96687:"e87414ff",96756:"9b807ab4",96774:"f72ffcb3",96861:"f9e15cb3",96916:"0f94b704",96926:"90ac4cea",97006:"0da448cc",97180:"51ca3300",97241:"0891f07e",97310:"de1ec67f",97338:"51424d9b",97457:"8bb6adae",97462:"5605d7e3",97466:"cf16dc1a",97628:"2dc7cabf",97659:"a45fefbd",97668:"200788fe",97680:"630e8bd2",97746:"cd0435fa",97773:"2f210360",97795:"1537ed20",97807:"3935fa91",97815:"10efff8f",97920:"c95888b8",98055:"b353acdf",98211:"92c0ab9a",98224:"4768e575",98253:"e7e994a3",98285:"39c23a95",98431:"f7056ff5",98471:"126568f7",98478:"659a22f6",98488:"2d922c51",98535:"9d32530e",98566:"98a9fd57",98619:"a76beb4d",98647:"66883c80",98650:"439c1c72",98685:"a809a160",98764:"4d4c3891",98853:"699feca3",98905:"bbad7412",98906:"bf476074",98915:"bfbe7bf9",99200:"393329cd",99296:"62a2c345",99344:"0b2758c5",99354:"e1807f55",99444:"e17a6dfd",99469:"0e7e3ae5",99523:"bbd1b109",99544:"448445b1",99557:"0d4acabc",99622:"89517064",99635:"a8477af5",99669:"39bd1d43",99677:"d145929f",99802:"08339b8a",99816:"f0897d9a",99871:"8d31e216",99917:"bc60a436",99969:"ddde681d",99988:"1f182e3b"}[e]+".js"},n.miniCssF=function(e){},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),n.o=function(e,f){return Object.prototype.hasOwnProperty.call(e,f)},b={},d="rancher-docs:",n.l=function(e,f,c,a){if(b[e])b[e].push(f);else{var t,r;if(void 0!==c)for(var o=document.getElementsByTagName("script"),u=0;u=d)&&Object.keys(n.O).every((function(e){return n.O[e](c[r])}))?c.splice(r--,1):(t=!1,d0&&e[u-1][2]>d;u--)e[u]=e[u-1];e[u]=[c,b,d]},n.n=function(e){var f=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(f,{a:f}),f},c=Object.getPrototypeOf?function(e){return Object.getPrototypeOf(e)}:function(e){return e.__proto__},n.t=function(e,b){if(1&b&&(e=this(e)),8&b)return e;if("object"==typeof e&&e){if(4&b&&e.__esModule)return e;if(16&b&&"function"==typeof e.then)return e}var d=Object.create(null);n.r(d);var a={};f=f||[null,c({}),c([]),c(c)];for(var t=2&b&&e;"object"==typeof t&&!~f.indexOf(t);t=c(t))Object.getOwnPropertyNames(t).forEach((function(f){a[f]=function(){return e[f]}}));return a.default=function(){return e},n.d(d,a),d},n.d=function(e,f){for(var c in f)n.o(f,c)&&!n.o(e,c)&&Object.defineProperty(e,c,{enumerable:!0,get:f[c]})},n.f={},n.e=function(e){return Promise.all(Object.keys(n.f).reduce((function(f,c){return n.f[c](e,f),f}),[]))},n.u=function(e){return"assets/js/"+({92:"8996d840",151:"3fe327d9",218:"c2d822c0",426:"e81f13ad",470:"c4a66de2",543:"4dd994d7",560:"8773a1b3",692:"c524dfc1",803:"a8537194",858:"079e1e8c",876:"31dc42bc",1014:"9285fddf",1074:"acf37ba9",1188:"7e8c5b11",1233:"ebba9620",1272:"66e7ae78",1307:"a18d7c59",1441:"760c555d",1484:"c2f39bde",1665:"c6be4ee7",1847:"4697ba72",1995:"d9c31cac",2073:"97546b1a",2207:"0ba5f5f4",2309:"bee19150",2334:"f10d4d5c",2371:"6e9e1aa3",2463:"dd78b469",2476:"e3ab7e94",2535:"f75a5cef",2746:"288ff2ff",2786:"b6c428f4",3181:"df3f6597",3254:"b204cf5d",3260:"5672471e",3299:"c5dd4a56",3445:"11de819d",3776:"be92b392",3957:"a8523539",4180:"516de1d4",4215:"ca1329d5",4267:"bfc57044",4311:"d4fe7dbf",4397:"123b9f40",4493:"eac4d15f",4494:"99c6e5ca",4502:"58a7dbd1",4583:"1f7fe892",4589:"b650d23b",4803:"c3fb3938",4947:"6cb26668",4983:"b2bece66",5008:"4b646b93",5093:"c7fc4956",5099:"5c5b3f41",5105:"cbc79ed6",5118:"a0b4884b",5230:"febee244",5280:"92463dfc",5324:"42448ff8",5370:"4d4788cf",5418:"49d26382",5706:"f5713d99",5839:"22da2c46",5916:"94311af9",6054:"79138131",6061:"0c597aaf",6162:"95944931",6379:"6652b611",6495:"dea14605",6508:"9775b4be",6592:"d8fb889b",6617:"2f0700c3",6694:"31322e9a",6763:"bec7d502",6810:"40594ce9",7070:"ddf778e2",7297:"15045cd2",7366:"96f0cc11",7450:"4ee3153e",7573:"a04b778c",7587:"245584f2",7654:"1a00afd9",7658:"4dbeca1a",7670:"6e905236",7703:"9470bd0a",7911:"5abfffa2",8038:"40ec24e7",8092:"c99b8ea8",8145:"18e3f229",8226:"ff115ee1",8281:"d2270344",8282:"32a5bc4a",8362:"87aa1598",8392:"b7879678",8473:"28134557",8491:"0f52acfd",8562:"9692c10a",8631:"2d15e68a",8644:"55417783",8701:"0babb5d8",8769:"e57bdfae",8799:"b296451c",8899:"d50a1aa7",8901:"b7f99883",8924:"f9fdc755",8952:"16647ef7",9017:"34cd303a",9136:"26e86bf1",9324:"cabb6017",9391:"842308dc",9575:"52eba42c",9595:"c6a1800c",9613:"bec4702b",9644:"2aa62228",9712:"afde3945",9806:"d30e3ce1",9877:"c520a1a7",9899:"07df0b9e",9909:"115e2606",9981:"01a36a7a",10003:"390bc0ef",10025:"732886a8",10071:"da92d5c0",10146:"15015618",10195:"501facfc",10246:"ca63b941",10325:"de90ac60",10355:"baf47ad6",10438:"c48acb15",10557:"89b8bc8c",10571:"a6a82698",10632:"317f5e70",10814:"cfa5fe6b",10865:"cf094c24",10889:"632d2cf8",10923:"4a2eafbd",11018:"704f3734",11123:"bf37456a",11139:"fba918c0",11212:"eaaa0a94",11303:"124c01c4",11367:"60b9fd82",11405:"e8ab8a58",11532:"72b05f6d",11569:"1116174c",11785:"7b134385",11810:"cbe55200",11835:"85f56c8f",11842:"9570b89e",11955:"3e2485cd",11986:"719764be",12048:"cec2ca1b",12231:"476dfafa",12428:"389c4d39",12463:"762c1d62",12495:"ac0e4adf",12547:"da222b02",12584:"56c34b6c",12616:"db1eb9dd",12748:"2d36afb9",12752:"22cf9a33",12821:"20bedfa8",13e3:"45e55f02",13073:"0aa2529e",13085:"1f391b9e",13097:"719ba419",13134:"f527ac01",13276:"c12e27a4",13290:"7875f3e1",13297:"36f06557",13438:"5650f021",13453:"0bb2a061",13546:"2a07a4d0",13579:"8bcd2d6e",13715:"b81ecc9d",13838:"4688ce4e",14075:"279ac42b",14114:"31c44b3c",14166:"5f6facf2",14374:"47d0a33a",14418:"f85955f3",14512:"1d8e9cc6",14515:"b3807136",14525:"163f63fd",14754:"e9b3839f",14755:"5f9f26e3",14950:"bb1597c4",15090:"77b0bd90",15149:"50194363",15403:"eedf7e04",15474:"01533949",15619:"657a47a9",15640:"059f0361",15708:"a5df451c",15872:"17e07a3d",16008:"22a8b095",16137:"2239996a",16183:"5925a681",16290:"74030caf",16692:"b3e21373",16861:"ef033983",16914:"0aca2b4d",16990:"74f64fbb",17088:"70282811",17287:"f9c0e5fb",17351:"99286acb",17397:"964c8b6e",17459:"7169e4ce",17538:"89cb8e91",17659:"c38c7bb2",17670:"fa33d8d9",17726:"36d24dc3",17870:"353be3ab",18004:"4345bac2",18064:"b7117ab0",18104:"ac70c4fb",18165:"66b1ee6e",18291:"ae6d5f2a",18329:"8446b2bf",18368:"713c61ab",18428:"eb66573f",18445:"18ed944d",18617:"3b7ee216",18820:"736351cc",18846:"49c30421",18856:"6934d7e8",18911:"6781e7b1",18914:"d9f62a80",18953:"c03c4d1d",19098:"fd0c9593",19123:"643d5fb0",19179:"c2c2fd7f",19214:"f3b333b7",19218:"c7ffff18",19465:"925e00c3",19489:"53ef77ca",19510:"aed778da",19614:"26d4ccd7",19776:"68ea2107",19808:"b2e2d2bc",19853:"923177f3",20080:"6658ac42",20175:"3f076996",20334:"75f02af9",20357:"bc855d82",20425:"906a6882",20689:"97726573",20770:"31df4207",20787:"068bc51e",20988:"e17d56b8",21156:"a9683a17",21167:"65cc8405",21187:"3999cc2b",21210:"2e408315",21245:"13ecfad2",21419:"a6d2d815",21538:"529bdb84",21705:"68ad2298",21739:"ae21521b",21911:"93095eab",21931:"6227d3fc",21958:"37885d63",21981:"594057a9",22007:"4153b51e",22145:"73b78ce8",22245:"cc09ce29",22302:"21e2d8cc",22376:"39e94c6a",22460:"d07f32cc",22483:"04061093",22520:"8260111c",22546:"f7bf0eb3",22675:"eef53622",22856:"597e9a84",22894:"e4643a61",22895:"7f6c3274",23044:"ae04538d",23212:"7a30e7bf",23345:"064ee7ec",23402:"ac428ba7",23561:"011dfd7e",23791:"6228436c",23798:"37a196ea",23840:"ddc27281",24038:"5ee60ab1",24085:"0cb7b855",24242:"9baec194",24273:"fb54213f",24404:"4a870cfc",24521:"2e0b84cc",24681:"96544142",24741:"c732fadd",24836:"1907685e",24954:"d85b2a73",25215:"f573510a",25226:"d32f70f0",25279:"9e916adc",25350:"e02c1ae0",25438:"4de12aab",25567:"059e8463",25589:"05df9a2c",25863:"cb98f550",25875:"8dfc90aa",25877:"76440c84",25991:"09029ebe",26044:"639ce40f",26075:"447c27ad",26250:"ecc8df09",26283:"807ae1d8",26353:"e1f00143",26446:"83fe0eeb",26725:"d11f8d40",26743:"b8e667c5",26875:"c6ff2c51",26966:"99951bef",26976:"e647d8cd",26989:"9297bab4",27061:"2538a207",27063:"aaca71ce",27301:"41f347e6",27349:"b8b5cd27",27392:"9c496c3b",27468:"7114f94b",27557:"ed602548",27565:"11dbcd21",27656:"811b01de",27717:"d5c17d8e",27740:"ca8a26d9",27837:"ae3b439d",27918:"17896441",27987:"d189a4ea",28320:"30c0e3d1",28337:"c5969871",28491:"79a36cae",28605:"7945214a",28671:"0ac5d4d5",28768:"31f34f63",28823:"e0737014",28905:"8c39340c",28934:"0f79a30c",29143:"d4174923",29294:"497955f1",29354:"0eeb141c",29389:"154ed32a",29449:"fe10bc2e",29514:"1be78505",29617:"fb1c0286",29679:"e1caf301",29705:"b368f20d",29738:"eca70f54",29795:"6a831fa8",29797:"5612f5d2",29890:"e67f27d2",29956:"b72bc8e0",30192:"36a01650",30225:"e5c88a03",30285:"42e58cd2",30337:"e54100d7",30362:"111896fa",30382:"acc5d3e1",30394:"103fedbf",30538:"9cf07083",30575:"49423f53",30585:"df7f733d",30654:"d1838834",30685:"271c8ea4",30836:"0480b142",30949:"41875a9c",30951:"8f57dae8",31032:"f594ef05",31060:"c7376ac9",31076:"d502d095",31155:"e8c4ad4a",31190:"f710fd1b",31377:"c1dfb946",31510:"b9049539",31558:"a3b4c9e1",31732:"bd671f46",31749:"132ebbf0",31863:"2f7718d8",31869:"6ab0b16a",32163:"0700b08d",32165:"a677df94",32266:"203416e2",32356:"33aab58f",32411:"fd66e915",32513:"eb71bfd3",32527:"08736ebe",32666:"27dce654",32691:"9e504a9f",32697:"9083e0c6",32714:"d161c74d",32959:"6618d504",32991:"98580f1c",33016:"bab2a247",33017:"efd15b1e",33036:"ef2b6bbe",33083:"d4d705af",33084:"f2ae3bd8",33183:"d99ae185",33188:"ae2e7981",33296:"aa943c00",33306:"70013d1c",33458:"d077980f",33472:"40b3f3a5",33550:"a2ced858",33620:"6de600a6",33657:"de7ce0d9",33673:"e5970534",33833:"6caeb7fe",33986:"1413ddda",34026:"f06e7b75",34177:"52f50aaf",34296:"124e7d46",34334:"ea4b73b6",34428:"fa26d017",34454:"15bf0260",34541:"1ac8272d",34596:"aa0d03c6",34654:"c0e5b22c",34663:"dd08b676",34735:"212b5690",34736:"12cfda90",34746:"07422b8c",34756:"d986569e",35033:"c56b385a",35150:"1c0b26bc",35153:"ae2195e0",35191:"cd5409a7",35491:"3f050504",35637:"21944ac9",35741:"92f028ed",35761:"e761761c",35903:"e671ecfb",36097:"456b18bc",36175:"35cc0fcd",36208:"18549e98",36425:"c17a430d",36431:"9b56f2c9",36433:"c0dc84f8",36531:"2a21f987",36537:"66526812",36611:"a18ac7cd",36812:"c9185dbc",36849:"3c2b7a36",36883:"45a8f67d",36913:"242b8d1d",36917:"faa4029c",37098:"64ff53fe",37200:"532eddeb",37258:"5247f177",37309:"7867d803",37383:"90433446",37534:"0263a9d8",37634:"79939582",37702:"53ab2698",37708:"ed1e497e",37733:"89f61296",37742:"f451ee7f",37784:"d0cca6f0",37874:"30593c76",38009:"e87f9614",38193:"c48eff13",38330:"912cac72",38391:"759e6d25",38395:"b04db539",38413:"d11c5d82",38434:"ab49343e",38457:"aecbed3b",38550:"48180ece",38636:"74d381d5",38708:"3a856ca1",38737:"bd445969",38743:"0a5e8d28",38897:"8c6a05ec",38904:"e80f9c05",39250:"9f172014",39516:"0f00b513",39552:"0078dbec",39677:"ff7f7043",39699:"b5145080",39750:"ac65bac1",40030:"384b6617",40132:"aed83937",40227:"3639695b",40337:"dc6499ef",40356:"c7e2e3b0",40655:"6a702a3e",40744:"829c4a08",40753:"84f0d5b4",40805:"f8be0529",40850:"6d7aa71a",40860:"14ae49f7",40873:"b8f2027a",41002:"51c407b4",41067:"c64fbddc",41219:"f4fef6c7",41392:"1ceb758d",41431:"bb1359aa",41742:"d2277319",41772:"2479b691",41830:"7f1be2da",41833:"d10e6edc",41869:"88207123",41903:"0fc70254",41974:"ec08512a",42100:"3a165f9f",42316:"a3910fb5",42350:"27884f99",42537:"1edbd8df",42653:"871e4b05",42743:"b5ad4633",42760:"5bf9dc54",42784:"1266c809",42799:"80107821",42820:"ff33a905",42856:"444d0845",42857:"b2aa480a",42989:"e2f2db65",43117:"f66a122b",43151:"27409706",43209:"504ec2df",43260:"f62e7cb5",43269:"21d75435",43270:"73975807",43271:"1eb23122",43332:"569a3616",43366:"e7edc475",43467:"5021852e",43607:"6034ac44",43816:"261d5fd4",43963:"fdd4431f",43966:"27d3c76c",44222:"03588a30",44225:"ee92e728",44457:"7a5b18f3",44474:"d9d2cbf1",44491:"1a34e69f",44555:"52fb2bd6",44611:"67edc1e7",44663:"d9477daf",44693:"966e19bd",44725:"0466c4d7",44955:"0def9989",45006:"96c94a5a",45101:"2a3c872f",45108:"fe59faab",45142:"4e37f83b",45169:"de031ae0",45221:"f466bbe6",45381:"0b9b2f7b",45413:"5cc76871",45417:"069921dc",45422:"eaf2a302",45555:"e1f933b5",45613:"6c7431d8",45725:"51899891",45976:"c71b92ed",46192:"17d125a0",46515:"74120125",46644:"e2c8de9f",46730:"219a13ac",46743:"c7b7f7b0",46752:"a9b929ff",46762:"a9a6e797",46857:"0f3d6737",46922:"7c6ad019",46979:"3876c50d",46984:"a4ee4544",47081:"e600514a",47161:"b28c2f9d",47162:"d589d3a7",47183:"4006d464",47478:"98a9d113",47511:"3169280c",47547:"12e3789f",47561:"80425d19",47631:"2c5be4eb",47672:"432b54cb",47674:"e1178654",47805:"93c52216",47833:"21e977bf",47849:"9c807b97",47862:"e565549d",47934:"acf7412b",48060:"0e5b1614",48068:"fab6d391",48213:"9eb3b065",48289:"40488fee",48351:"e5c2618d",48355:"fbd6426a",48461:"496e6921",48496:"32c0e07f",48617:"399a7c13",48725:"b824bc5f",48754:"15d1b497",48771:"fc770245",48942:"d1da5adf",49027:"6f040d42",49028:"09482661",49112:"7397dfd6",49119:"c7f6e498",49153:"5245b6ee",49156:"7fd337d2",49353:"21f9d022",49681:"bf2d01cd",49688:"de923e65",49870:"984cad2e",49872:"3f0450cc",49900:"a0272590",50114:"ed230530",50153:"8a625965",50177:"a463b0f9",50207:"d217fcbe",50318:"7df78dc1",50381:"01629d75",50503:"657944b3",50506:"dbbb077d",50558:"f2d214ec",50657:"8282b4fa",50675:"7972cece",50677:"20f200e1",50948:"380fecf8",51019:"5eebd93d",51029:"812a926f",51097:"d568ae1e",51136:"a28030f8",51409:"4a7dd70a",51410:"9c8d9de7",51443:"7e4b5909",51484:"49462d91",51529:"8b8c449a",51565:"02d9cd64",51587:"14a6764b",51599:"beab3968",51869:"f82e4539",51921:"b6075528",51965:"f6efba93",51976:"e2e05a0b",52079:"debfcdd8",52123:"cb87c0da",52188:"a8df8be4",52231:"6bee34e6",52239:"695dc145",52242:"84f114cd",52314:"00d28359",52428:"1cb07aec",52480:"4e60a6b8",52508:"c43bcb58",52675:"f0f73c23",52685:"c3e299d4",52696:"eb00bee8",52746:"c0f3a1e1",52764:"5b27f948",52801:"d97e8ff5",53294:"c67f263c",53769:"806af469",53776:"066acf59",53833:"9c8726e9",53839:"04b30511",53926:"d434dab0",54187:"2d46d1be",54263:"aa15e9b6",54289:"499751be",54355:"dc8ae3e6",54358:"cb89c0b0",54487:"fa09d98c",54544:"2d7dc328",54551:"5a8dd044",54648:"3ebf75d0",54653:"a306c7cc",54660:"4d3ea151",54772:"8b953e29",54857:"60158128",54898:"3ec47db2",54977:"4470927c",55085:"fbdfd47a",55104:"f4a8d251",55321:"8928903c",55408:"94b85d58",55555:"3ceba367",55598:"d8399510",55610:"fa4d2b81",55757:"fddbdb1b",55770:"941d83e7",55776:"4d6bbc69",55831:"228732e2",55840:"d3e79596",55845:"a9426322",55851:"eb31c816",55907:"cff158cf",55940:"3391b670",55977:"c0c252da",56136:"4997d94f",56200:"5e6b0d00",56205:"b358fc39",56217:"d3d19f51",56238:"f06e9ffc",56531:"9af6974b",56749:"3302a6f3",56871:"bc0f58dc",56874:"f437947b",56876:"c421cead",56918:"616d12ed",57166:"72feaf7b",57171:"17a1d54c",57246:"863b9fb4",57256:"70a09d1e",57338:"3d4bf2bd",57412:"b75f7b1c",57506:"98cf1a5f",57526:"03ba2def",57559:"201c43eb",57646:"181298bd",57748:"3551b602",57779:"28f93af9",57793:"5fa42b25",57890:"ecb16b68",57953:"2422c243",57965:"f415ef48",58053:"72927799",58202:"0d130fff",58270:"8c5009e2",58540:"f2abfe5b",58662:"ecd45472",58860:"9473047a",58867:"7ea23e33",58941:"4e591fcf",58959:"19502856",58967:"6826b540",59080:"1a460f42",59104:"77b8d4dd",59174:"21284f6f",59359:"3de9f572",59373:"e4b62490",59457:"87c82632",59694:"5766b5de",59831:"eb784468",59868:"2ee6a2d5",59925:"7c98b1f4",60155:"4b66d153",60165:"922b75ce",60275:"f44c9e05",60486:"51725525",60533:"3743955b",60593:"f22b2eb2",60757:"9be4d7d4",60849:"17961e1c",60862:"a25c917a",60905:"0aee8de5",61184:"4dc92296",61215:"5117dde5",61228:"f77e7069",61242:"5fe1b138",61251:"52372a98",61295:"ea2401a8",61333:"0cef2a3a",61389:"186d0490",61465:"a5a5bf55",61470:"6f77a78e",61497:"c595ffed",61681:"fb6539c1",61719:"e66c9d98",61794:"a090aac6",62030:"4070292b",62189:"dfe579f0",62276:"905ac3d3",62289:"647da62a",62384:"1141ea08",62489:"edf14699",62520:"7e36e062",62524:"f42b04e0",62608:"d1268a69",62888:"db9c9d9c",63093:"5b84cd36",63310:"8e54e8e7",63320:"583f9b00",63554:"d14243c6",63569:"980cffe6",63636:"b381c227",63671:"e1cfd688",63707:"882910b1",63716:"0cef0e21",63758:"d9b1f215",63791:"89ef02b1",63883:"5bf10cd6",63906:"0d1d8293",63953:"13aeb527",64044:"41a026b3",64130:"9f9f17ce",64158:"165d4317",64348:"aaacf44e",64415:"f18723a5",64475:"1ee31240",64517:"777346bd",64711:"c04d9b23",64733:"a98d3c98",64792:"5e7cdc20",64805:"4e778939",65111:"5e10776b",65279:"02ba2fd1",65345:"b39ed1dc",65592:"4c1fabbc",65598:"f3bc9628",65608:"0e43428f",65643:"61f865de",65732:"9b245343",65767:"dc76d1e8",65768:"25256696",65789:"24fa53ab",65822:"ec7017b8",65909:"5c97c651",66147:"5da65b2e",66181:"1f123095",66197:"74e1a3cc",66207:"af725113",66280:"9da27c7c",66373:"5be17b65",66418:"4b2197b8",66464:"5c0fad06",66575:"54567ab8",66598:"a775dfef",66626:"cfcf8c0e",67198:"8a62b79e",67431:"11943549",67453:"b6678181",67570:"c23eff0d",67751:"67399e1f",67784:"89fb135c",67796:"a004d986",67964:"883b440b",67986:"a1237ed4",68346:"f8e2f315",68453:"2220f4ce",68498:"0f1573e7",68677:"3751e155",68725:"0ee9058c",68750:"83df63b5",68862:"2f528031",68892:"24711014",69078:"3db0f83e",69360:"9d9f8394",69466:"1a0d3e73",69550:"983c3078",69595:"c1aa0c2f",69601:"0568624c",69603:"1c8d7345",69775:"6dbebcad",69872:"41a14838",69890:"f1f0bb48",69958:"5778bf09",69966:"833be8f7",70113:"11d71a1a",70124:"25050c59",70178:"d0d21d6b",70195:"a3d1f23a",70210:"38dc5db3",70231:"e46687b9",70258:"b1836b3f",70269:"5c672707",70520:"2a28c099",70602:"9f460c0f",70700:"23c64341",70747:"fbab1324",70804:"57a293f1",70807:"e5a2f024",70981:"8a8ac7df",71090:"79021e97",71125:"b788ce2c",71392:"1752e6fc",71416:"4d6440cb",71598:"d6797715",71651:"b5d7eab2",72014:"b3ad459e",72071:"389e6565",72103:"73f20b10",72209:"73e43e7a",72290:"0418a177",72301:"ce99103c",72406:"1acdf7ef",72475:"ff0800af",72514:"ae74935f",72523:"669a2232",72846:"12228ce8",72884:"ac285d4b",72948:"e7a1ff37",72949:"19d517d3",73021:"21b3bf6b",73034:"da524951",73038:"17809026",73050:"036e814b",73051:"f84ec093",73066:"fc1495c4",73094:"91f31bf1",73134:"b1ceea70",73254:"bced4641",73272:"d706d118",73282:"a1d3d12b",73292:"83e73561",73299:"77fd0f9f",73318:"3435c6d5",73630:"e84cabd6",73679:"e4815a9d",73706:"78d162a3",73714:"f12a9c75",73733:"e34c6ba4",73794:"aaf2ebbf",73804:"49059727",73813:"99efa9b2",73882:"f3f9afb2",73919:"c3f03a9c",73920:"122b796c",74085:"a792cae3",74111:"d058da0d",74162:"4f459a7e",74188:"905f92f4",74291:"bdd2db00",74352:"258c4920",74438:"d1f46e88",74812:"230c9e6f",74867:"9d2e93b0",74877:"9f56c61f",75025:"83c1f296",75114:"2170c9a1",75190:"bf643b2f",75452:"3181ff19",75545:"442e8a3d",75658:"766f5345",75799:"266e07ad",75963:"dca72a2a",76297:"a4277995",76477:"94715af4",76492:"a08daa90",76709:"6116bf24",76724:"f597afa9",76751:"07d09572",76902:"91ff2ab8",76921:"8bae5537",76964:"bb2c716e",77103:"18e435b6",77337:"6b2b0f3f",77378:"e5ecc38a",77394:"85a62993",77525:"9c79c61e",77534:"55710cb8",77605:"d2ae1f82",77714:"b497f2e2",77813:"686c6da9",77982:"43a61436",78055:"b595542d",78140:"a44d65e1",78404:"cb3bd380",78442:"0743c229",78477:"e2a73b5b",78499:"6b5a695e",78545:"f20bd9cf",78595:"36c182da",78729:"5c84170e",78770:"2f6bbf60",78784:"d2095685",78909:"8872cb84",79140:"6ae101cf",79187:"e926511c",79338:"f64b12af",79457:"2bff2efc",79458:"d503b0b0",79502:"7aafa071",79618:"8ea4be35",79683:"ba4608ed",79705:"2b28e252",79794:"70500b4b",79871:"5a626cf4",79882:"5558815a",79959:"38bbb6f7",79980:"564b139b",80053:"935f2afb",80102:"f3d52ace",80180:"f9758b2b",80258:"0b419609",80298:"0a96855c",80350:"7deaffec",80352:"c29e0dc6",80366:"43fd43b2",80382:"9f6922d6",80395:"a0f27e39",80471:"f4a489fa",80481:"233bd232",80597:"633b4268",80683:"7809eda7",80707:"d9bd109c",80742:"9ca34565",80757:"3b19df91",80781:"c813dfb6",80784:"27a0e9a6",80922:"e0c5b57a",80929:"75f97e01",80957:"1e04755c",81026:"2de82f74",81113:"dc993438",81131:"88fede05",81147:"5b356f0c",81206:"bd1f4d4d",81324:"091dfa99",81475:"32b9dfa4",81500:"90cb80f4",81519:"51aa6ffb",81623:"e685fe7b",81627:"7f615251",81674:"cc1de87f",81720:"72e3ea67",82009:"a73e121d",82048:"3f5735fe",82161:"578e646f",82229:"31246fe3",82247:"c903ba62",82283:"b7c24ea9",82384:"b6ad761b",82385:"112d7f90",82500:"e47c2663",82724:"31d59ae5",82934:"eb7b1076",83056:"23b1efbb",83058:"3073ccb9",83075:"469439b3",83081:"6a63eeda",83082:"7a3fef43",83100:"68cd29cc",83102:"7a399052",83210:"a8803ad0",83231:"b28b315b",83352:"9b061d60",83353:"c8a4fc71",83425:"2121efdb",83454:"701689a3",83470:"bebb551a",83488:"a5aa0181",83544:"5b9d5773",83651:"0e1330ab",83878:"7ba381c4",83889:"34d3812a",83969:"cfb30de5",83995:"4ee76210",84002:"63dcc201",84024:"eed3d70f",84093:"f52c5b6c",84146:"8ae68021",84170:"235b22f9",84305:"37c8d80d",84501:"b9300de8",84549:"f4b387c6",84585:"5df3ccad",84668:"801615aa",84892:"72f20b9a",84936:"c86089cf",84994:"15bd7fb2",85098:"a732a816",85158:"36054b2a",85165:"fc816072",85498:"d35253c3",85587:"636f78d4",85657:"8fc50042",85928:"6b86a004",86006:"a52caeea",86007:"f59cc2df",86056:"df228eb7",86062:"1fe53564",86079:"e16f3e23",86080:"92261483",86169:"62180679",86229:"740cfbc5",86459:"349c6fe8",86479:"f114c040",86505:"4f44017e",86593:"76708471",86717:"02c13856",86730:"05a30404",86740:"16715f67",86746:"4c21325e",86751:"c8740552",86883:"6705557d",86955:"09139d96",87069:"98dedf47",87293:"41b84bc1",87302:"bbc5be04",87376:"14ed99a3",87439:"e46f8a72",87458:"609de602",87496:"8250ab46",87554:"1a04ee3b",87606:"cddfa015",87964:"7925dbd8",88055:"eb00ac44",88085:"cd3e9f7c",88092:"f4695122",88127:"2c9009d3",88167:"65039b67",88205:"c6c759c1",88209:"2e94af40",88262:"0d014f06",88438:"d49aaf69",88445:"2f54a133",88469:"60c90a58",88661:"510af3ef",88768:"00a8cf8f",88812:"271688ec",88823:"dd93d2e4",88990:"804c7efd",89067:"d8eecd3a",89118:"b3428692",89147:"3e7201c4",89178:"c157ad58",89221:"8b2e9ec2",89244:"de7959df",89284:"8bb9a2f0",89357:"4708e904",89383:"38c58766",89473:"214808df",89474:"3c095580",89573:"0775542f",89671:"dc482cb1",89730:"11740645",89782:"b16ab873",89839:"6c1d1c3e",89938:"412fbf9f",89961:"2da1cf89",90129:"af3a8c26",90134:"81e479c0",90143:"fe1522c6",90216:"83d651a6",90269:"c9a0d8ae",90475:"97ae6f54",90674:"85028062",90802:"8acdc9b1",91077:"cdac035e",91091:"6b26ffce",91215:"df8bf24c",91360:"b0ff3ac3",91483:"8b2041b0",91565:"f4b833b3",91692:"18c961f6",91702:"9afefd1f",91743:"8734afb6",91789:"b18e31b7",91859:"748bf8b3",91869:"dd080071",91951:"fb9fcb5b",92099:"9cd05c6e",92289:"76e8764f",92296:"771fc4e7",92412:"be3f031f",92485:"1ac14023",92528:"96947e44",92627:"edecde5e",92657:"e998e5db",92778:"4f6dcf60",92993:"37ac39cf",93262:"168ac9d4",93369:"eb7fdb35",93420:"870fdbd7",93441:"ed765822",93526:"8b600e92",93627:"edc9c83a",93784:"e028d6df",93853:"f1c8cdb3",93857:"ed232bb1",93865:"c9869c67",93889:"31ca016c",93923:"eb3cc724",93927:"6304a1c8",93931:"a198644b",94124:"8a1c07a8",94205:"3c776bab",94232:"1b0c6d7c",94321:"cfa759f6",94398:"a2dfdd17",94594:"dca25a09",94727:"15524dd1",94747:"ca67bde4",94761:"e13750cb",94986:"57b790ef",95035:"6ecc7926",95129:"2d2a049a",95163:"7d2af5f7",95215:"6e1cd7e3",95406:"49a6cb80",95669:"7afb09d3",95787:"160c20b4",95836:"89188be0",95924:"060bb38f",95932:"392750e5",95986:"92da714b",96034:"2e39e31e",96203:"67e456bd",96363:"000b0b3b",96391:"535687f0",96403:"7df29312",96440:"27082a20",96481:"89e79058",96540:"818cdfcc",96543:"dcbc72b6",96571:"aac2bc09",96684:"83bc5b60",96687:"2de98f94",96756:"96e5a9c0",96774:"1bb63d8d",96861:"886b0cec",96916:"1a412b79",96926:"5731ca57",97006:"5a7ef470",97180:"b0bf5481",97241:"553ce7ec",97310:"17aee925",97338:"f8cd448d",97457:"fe5276da",97462:"053401a3",97466:"bf1c9a15",97628:"cdda4d34",97659:"50629e36",97668:"0ceb5061",97680:"6d809921",97746:"b18e806a",97773:"90ab9f19",97795:"0ebd1ec2",97807:"20d125e4",97815:"501e3680",97920:"1a4e3797",98055:"8d2cd206",98211:"1411c025",98224:"dfc9ab0a",98253:"1468a817",98285:"387a4238",98431:"4b471a3b",98471:"a584238a",98478:"c383dea5",98488:"9a03e1d3",98535:"cadf7bf8",98566:"5e3cd947",98619:"f366db13",98647:"3acaaf8b",98650:"ee30f3a5",98685:"fd02bb74",98764:"c8767106",98853:"b7192f86",98905:"68132c44",98906:"5c9858b7",98915:"4b1580d8",99200:"4f286fb2",99296:"1e28d2c3",99344:"2615ed93",99354:"fc542f76",99444:"4eb132b7",99469:"2f86cf9b",99523:"d0123614",99544:"8d0b1d0b",99557:"bbcb5258",99622:"a920fb26",99635:"f5172bcc",99669:"44bcd317",99677:"a8412436",99802:"6732b456",99816:"ff304de5",99871:"47d2b372",99917:"100fe9a5",99969:"38080670",99988:"7a6a8bb0"}[e]||e)+"."+{92:"535a28d6",151:"a5cdcb49",218:"8684d373",426:"2ceaf3cf",470:"6421cc01",543:"4a279379",560:"be539269",692:"46bbb018",803:"353b7783",858:"a68a89e6",876:"8363b35b",1014:"a57b46d7",1074:"68903e7a",1188:"a250d3a2",1233:"5be96823",1272:"d93b4c7c",1307:"391f5aac",1441:"db3fd9e1",1484:"4f65d1f2",1665:"e68084fb",1847:"623dba51",1995:"ca50bf4d",2073:"d4a48703",2207:"480eeb69",2309:"31206cfa",2334:"5b2b55d9",2371:"8299e86b",2463:"f3c47d3f",2476:"dfb82135",2535:"566197c7",2746:"9e6c7afa",2786:"fa13404e",3181:"b18adae0",3254:"36ab8c80",3260:"42cf43fe",3299:"aa0ea155",3445:"5f4bc9aa",3776:"0e64b3fa",3957:"8d0d1248",4180:"a408cd6e",4215:"a862d797",4267:"6f102b8f",4311:"4da50505",4397:"c7f53b9c",4493:"7f3d26b6",4494:"4a9bf2e4",4502:"dce80dd8",4583:"078ddbf2",4589:"7a41fa7e",4803:"9cd5d669",4947:"324c5451",4972:"69f6cd4c",4983:"7f881d5a",5008:"eaf66e77",5093:"e7a5d816",5099:"c48aeccc",5105:"524b9a58",5118:"4b3c58b0",5230:"ef60d17f",5280:"2a82facd",5324:"98b4bb3a",5370:"00b8a8a0",5418:"b9620785",5706:"3e3b7fe3",5839:"d9cb4e29",5916:"7849d2c4",6054:"938e62ba",6061:"1d2c2d4d",6162:"e47c65b3",6379:"ca349df6",6495:"7621047f",6508:"2215a1cb",6592:"6e3f4a98",6617:"f7487a3b",6694:"9adc7017",6763:"d19e12c3",6810:"4e98c634",7070:"6cda2c58",7297:"7f398627",7366:"5fba47be",7450:"94e1a824",7573:"bec8975e",7587:"973f6cae",7654:"94a22298",7658:"c41d1243",7670:"cd93850d",7703:"33ce4beb",7911:"7b32e6ef",8038:"2953f7ac",8092:"20914538",8145:"f20dcb50",8226:"54bfa0a5",8281:"a2f34fca",8282:"2729ef25",8362:"0347c464",8392:"0151debc",8473:"f2f90f11",8491:"7c4dfb72",8562:"2a0d4ff7",8631:"3b7d9c8a",8644:"f3f2b585",8701:"b0fb3909",8769:"d8574234",8799:"14eaddb8",8899:"6e5fca44",8901:"1d811244",8924:"27c84b9c",8952:"e2206404",9017:"6474812d",9136:"0f06364a",9324:"2c99304b",9391:"80511dff",9575:"c07e693c",9595:"2a21f145",9613:"df557afd",9644:"176aa807",9712:"0e404c54",9806:"c9f442fb",9877:"a1a8fd95",9899:"0e843ea6",9909:"5692688e",9981:"25d5face",10003:"6e423100",10025:"403d1fec",10071:"87d20cc4",10146:"bbb17c3a",10195:"cfaf39fc",10246:"acbfa7c1",10325:"bd1f5b9d",10355:"12a31bcb",10438:"da5473e6",10557:"016137d1",10571:"4ec1f7bc",10632:"594222ea",10814:"8b907702",10865:"ecea7671",10889:"a6f345ff",10923:"feece7ea",11018:"ead209d1",11123:"554e5f3b",11139:"723813c4",11212:"2caf5eb6",11303:"4d3b04e6",11367:"fb0e1f3d",11405:"206041ed",11532:"d23e40ec",11569:"a94285d0",11785:"ff4292fd",11810:"fe5456dc",11835:"dcff2f39",11842:"c8fbe67f",11955:"8391db38",11986:"ea7c271c",12048:"53ee497c",12231:"7f8bf12a",12428:"c36a3e82",12463:"7ec08174",12495:"984bebad",12547:"2f76a18c",12584:"a7435ad7",12616:"70eac114",12748:"31995f75",12752:"fd4f5400",12821:"93459e3c",13e3:"4a8d517c",13073:"74574142",13085:"dde0024e",13097:"3ea41088",13134:"2ecd4487",13276:"5d87571e",13290:"ebf2cf40",13297:"d00ef79e",13438:"d2700d98",13453:"0c4b1f22",13546:"e600be81",13579:"2b3bdeb8",13715:"71205e7b",13838:"d4377bea",14075:"739f29aa",14114:"8d627851",14166:"aed7e56a",14374:"cc93a17b",14418:"edeb4322",14512:"1968686f",14515:"c77c96e2",14525:"580e9409",14754:"eab494c5",14755:"3400b8c1",14950:"1248d382",15090:"7812b21e",15149:"d4728d15",15403:"fd08573a",15474:"e0956e13",15619:"794c42f9",15640:"a3b9c30e",15708:"243ce5fa",15872:"58fbb54b",16008:"b4933583",16137:"0124a212",16183:"bc883d9f",16290:"df2f0239",16692:"57f42815",16861:"6233fdc8",16914:"7df5ffea",16990:"e46168dc",17088:"8561d378",17287:"174fc89a",17351:"56818b3d",17397:"30256042",17459:"c2828245",17538:"9749b315",17659:"b4aff8d4",17670:"c57740ab",17726:"a866eab3",17870:"38015208",18004:"ec67437c",18064:"7cb556dc",18104:"4300cd1c",18165:"bc1dc5f7",18291:"ae9c7514",18329:"b3065740",18368:"fc22ff32",18428:"5e6591a4",18445:"298e1915",18617:"1cfd3dfc",18820:"56c33705",18846:"c5b49faa",18856:"4ca9b82d",18894:"c2a7125b",18911:"ddbe1329",18914:"67d73ab4",18953:"7e83bf96",19098:"abbf890e",19123:"3a916cb3",19179:"a6089e1c",19214:"1a36a76f",19218:"c20a90d0",19465:"6d755f90",19489:"e9ac53df",19510:"b1004ab7",19614:"8e2e4952",19776:"2a91859d",19808:"36865124",19853:"6b053351",20080:"7247eff1",20175:"546fe057",20334:"82c2598e",20357:"d6cab0b0",20425:"17c43b8e",20689:"70429130",20770:"ed26f7e6",20787:"37d127d7",20988:"f7584e30",21156:"b857021c",21167:"e960c341",21187:"732014d1",21210:"6cffc295",21245:"ec97f924",21419:"e9d9e0a7",21538:"d061c47f",21705:"b67f970f",21739:"b0f75223",21911:"bfec9913",21931:"3214fba7",21958:"9228f8de",21981:"3c8f6b79",22007:"aa946fa3",22145:"780339a2",22245:"ef785d62",22302:"c19b31bc",22376:"a7bf3256",22460:"2f2a47a3",22483:"903ef67f",22520:"e52c9f94",22546:"832b4a3d",22675:"66bbe4de",22856:"fad9e05f",22894:"ce970b4b",22895:"d42022d3",23044:"6e0dc0db",23212:"844c5eaa",23345:"84af3ad4",23402:"8a4f10c1",23561:"da83b63b",23791:"f57b6ec7",23798:"1ebcd8dc",23840:"a54429c4",24038:"1f034733",24085:"c2c9d81c",24242:"2ff474be",24273:"0c95cf4e",24404:"5ecf5124",24521:"65b4ecfd",24681:"cebb1d3c",24741:"e3a8a7fe",24836:"dd819f46",24954:"539a5724",25215:"68f28a48",25226:"d9e19ab4",25279:"abf76f9f",25350:"4071d62c",25438:"38069028",25567:"ef9c0e90",25589:"ce4d8688",25863:"d9768176",25875:"e823fa4c",25877:"9d5ab0a7",25991:"cc00472c",26044:"5acb0300",26075:"2f1f7395",26250:"6d1612a5",26283:"6fc8539f",26353:"db8ed48d",26446:"9076570d",26725:"943e4570",26743:"60f90701",26875:"dcccff2b",26966:"94f5517c",26976:"46e6ad3f",26989:"cbefdaa4",27061:"6e07c150",27063:"f30e6bd9",27301:"5fae3af6",27349:"32a77190",27392:"70bba2a9",27468:"ac8975a9",27557:"a6669189",27565:"53041ee8",27656:"4046c415",27717:"40f5b827",27740:"34084d1e",27837:"d0b73bda",27918:"76f426ee",27987:"cf6b0594",28320:"568d9f6c",28337:"29610372",28491:"6e54b73c",28605:"a9b29127",28671:"1fe8c92e",28768:"b9bc9e2c",28823:"03bcdb86",28905:"9568f6b4",28934:"14414934",29143:"561b9e94",29294:"fd7ff693",29354:"d92106ae",29389:"1b18537e",29449:"93d59452",29514:"0d33649c",29617:"93372a7a",29679:"daf6c534",29705:"ead3527e",29738:"dd42caa4",29795:"78fb3f02",29797:"0d381054",29890:"c65a6b1b",29956:"62f45366",30192:"635c6f02",30225:"b332a40f",30285:"9fa253fa",30337:"ef460f86",30362:"157e6951",30382:"e91ea60c",30394:"d4cf9e4e",30538:"42fc5c45",30575:"ca729dc8",30585:"f16344bb",30654:"fd9ae86e",30685:"0b9e5cc5",30836:"16d4f8aa",30949:"f0268686",30951:"8d91020f",31032:"bbd394b4",31060:"2681286e",31076:"c4b72acf",31155:"7c8a6a28",31190:"ae8c4b48",31377:"5a585776",31510:"c4892a95",31558:"f2ca37bc",31732:"2d0959ee",31749:"d17a4cc6",31863:"2a49bfd1",31869:"9e3f3415",32163:"09a72998",32165:"5ca3d3a7",32266:"2568e26e",32356:"4a1a1537",32411:"adb121a0",32513:"0d0f9447",32527:"03e84f4e",32666:"046f323e",32691:"b8c35159",32697:"4021ba61",32714:"68ec6ddf",32959:"edadbe64",32991:"4142b884",33016:"d6a5bbb3",33017:"2a23a2e6",33036:"5ef1c102",33083:"725f4e22",33084:"5d3f8f53",33183:"21e25b89",33188:"7e136810",33296:"247b97f1",33306:"48360443",33458:"b1b01f50",33472:"79679fb0",33550:"bf194218",33620:"e942a8b7",33657:"6bf6073f",33673:"efdc9ff4",33833:"b4d6ee97",33986:"320402ff",34026:"1ef57b57",34177:"a37ab43b",34296:"0fd3340d",34334:"8bb020a5",34428:"ad7812f2",34454:"c4b4784d",34541:"e66106e5",34596:"cec5a879",34654:"6564127e",34663:"bcc2613d",34735:"a8e4e044",34736:"e84b46ba",34746:"38e19e8c",34756:"578b1313",35033:"f1b866f6",35150:"a7142914",35153:"0a1ed7af",35191:"b161842d",35491:"72d70e80",35637:"b9b4245d",35741:"4845c34a",35761:"a68f0e6b",35903:"63174413",36097:"ef799774",36175:"086fe722",36208:"d04ed314",36425:"1b8b18c0",36431:"9afd6801",36433:"4e70ffe0",36531:"25c88b11",36537:"f3c2f247",36611:"def7f39f",36812:"46d06d79",36849:"2f481f98",36883:"794fb5e0",36913:"0a2d05c7",36917:"bd26c62b",37098:"78cf5676",37200:"1fb18f99",37258:"8a211351",37309:"b3b9f586",37328:"c4bb0f6e",37383:"a33c1425",37534:"3376f20a",37634:"98651280",37702:"e849dfb3",37708:"d7f35daf",37733:"e57595f5",37742:"dec2237b",37784:"89924114",37874:"b3cd3de4",38009:"5dbe9819",38193:"368c7447",38330:"a2e123c0",38391:"5ec113ec",38395:"6d71e6b8",38413:"282b976a",38434:"b9f79fc7",38457:"2a7e410e",38550:"1c2e4010",38636:"9174ae11",38708:"a0cbc6da",38737:"747f8639",38743:"f2c2f193",38897:"4cdb2bf8",38904:"0537dc54",39250:"32a3c8b7",39516:"43f891d7",39552:"a27d8811",39677:"f8a103c7",39699:"7c64ad33",39750:"3b1dda8b",40030:"322abb77",40132:"102143e1",40227:"418dc0ce",40337:"62004783",40356:"506bd240",40655:"ea5e445f",40744:"1e3f0312",40753:"1aebb11e",40805:"d34eae98",40850:"d09ed0b4",40860:"80f282b8",40873:"25d4d83e",41002:"c7033b07",41067:"39374493",41219:"adac7d00",41392:"60cf29c2",41431:"c35a90dd",41742:"52a71b3b",41772:"4023cf8c",41830:"267ef385",41833:"2dc2ed87",41869:"726db2fa",41903:"03ce8bd6",41974:"904edc50",42100:"e5051585",42316:"302fffb6",42350:"6305c1cf",42537:"e49a7a3c",42653:"443fc0d9",42743:"072bf6b3",42760:"ebf286b4",42784:"35469de2",42799:"0b6ad83a",42820:"35724c0f",42856:"d6ace09e",42857:"5479f9bd",42989:"fcb77b9c",43117:"104220c6",43151:"fd459b3b",43209:"20600400",43260:"c286e838",43269:"1d7e14cb",43270:"bf61ff9e",43271:"6237c315",43332:"907da18b",43366:"c6357540",43467:"d637f5e3",43607:"7427052d",43816:"62e63002",43963:"9c2bb48b",43966:"f0a451a5",44222:"ed8c8f2d",44225:"c0c5ebd4",44457:"5213fe0e",44474:"1a6ab166",44491:"81d5765a",44555:"e7de74eb",44611:"0756d221",44663:"9701e166",44693:"57a4dbab",44725:"3b1c899f",44955:"633f75d4",45006:"90749b11",45101:"446078ef",45108:"7c3b1c64",45142:"dba8de6a",45169:"3b377223",45221:"ffc095ef",45381:"3ce5100e",45413:"dcf75492",45417:"1235c2a4",45422:"fa8f40ee",45555:"e74ebdcc",45613:"e866a17a",45725:"316f4bb4",45976:"81d02f64",46192:"e40fb460",46515:"f427e51a",46644:"6e9288fe",46730:"62944739",46743:"3865a2c1",46752:"9acb84b9",46762:"5e3e7da3",46857:"9e9b24e4",46922:"af84397b",46945:"e7eb5108",46979:"4f57cd9f",46984:"31cffdfe",47081:"35bb408d",47161:"8533fba1",47162:"dba2b151",47183:"053650da",47478:"3ae4bf40",47511:"506ae887",47547:"abdd93ca",47561:"b659ae1f",47631:"f03351eb",47672:"a9b32ec8",47674:"3266ac12",47805:"d8eae175",47833:"257cfcef",47849:"512be15d",47862:"4f9134a7",47934:"4004d791",48060:"f4db5ca0",48068:"27b01a32",48213:"dcd81cda",48289:"9f9a7a2a",48351:"6aef791e",48355:"c2ae0bc1",48461:"e6b67439",48496:"ec6aa069",48617:"870b2ceb",48725:"dda2579c",48754:"7d4e8b39",48771:"0d4847c8",48942:"d3f12fe8",49027:"a40deea4",49028:"2b4ae1d2",49112:"3d93b1fe",49119:"f0daaf36",49153:"99976ddb",49156:"942b3701",49353:"a3640717",49681:"077fbfd0",49688:"20dd248d",49870:"3287e540",49872:"bd87aada",49900:"c462969b",50114:"1d92a548",50153:"f22d794b",50177:"8532e1a2",50207:"751fec41",50318:"ba0eb5eb",50381:"6c6319cf",50503:"177f120c",50506:"fc7f21d7",50558:"89d8d15d",50657:"d5c9cfe9",50675:"d19078f3",50677:"c8d7ec86",50948:"3a98336b",51019:"e224ed56",51029:"143d535a",51097:"4cae1b61",51136:"db24d85d",51409:"5ac8a220",51410:"eb761c22",51443:"26dc5351",51484:"7be3e4dd",51529:"1692fd90",51565:"458f1b97",51587:"76860893",51599:"52bd9663",51869:"08e8cbb4",51921:"d2bb1240",51965:"aec35871",51976:"eaf6ad5c",52079:"38cf9ae5",52123:"2daaa322",52188:"8bf27aeb",52231:"e7e834a4",52239:"b28594d8",52242:"4aa49b65",52314:"432afe50",52428:"f1a94234",52480:"a4b0af4b",52508:"fad4a7bb",52675:"45463762",52685:"ec046fe9",52696:"b9c35dd9",52746:"de4a25eb",52764:"146811b5",52801:"c3344530",53294:"9dd47473",53769:"9b655c88",53776:"069cc32a",53833:"7fd988fb",53839:"f35e971a",53926:"0631ee1d",54187:"ef2414a3",54263:"3281e3c6",54289:"6fc8e35c",54355:"5feac870",54358:"0c6bd717",54487:"d621e575",54544:"d009e8f0",54551:"eb557c4d",54648:"a0e2fb3f",54653:"47d6882f",54660:"e1cfde55",54772:"2c8915b9",54857:"54fb9573",54898:"189783c9",54977:"58b5b73a",55085:"9bce3fc6",55104:"f9eb18ea",55321:"39624bbc",55408:"c96d77bb",55555:"83b2fe87",55598:"536d6b09",55610:"ee04da1e",55757:"045af70b",55770:"b2c46f62",55776:"48de51db",55831:"79ffd63f",55840:"7e9480b1",55845:"ac2d2b14",55851:"dc8c38e4",55907:"26937c68",55940:"3289b6d9",55977:"c0c7f24b",56136:"4bd18a00",56200:"a6356951",56205:"343ea0f3",56217:"bf84a591",56238:"0a599769",56531:"d6018180",56749:"dd5e7507",56871:"a43b3012",56874:"48f2dbfb",56876:"4f2f05dd",56918:"60cd2a96",57166:"fa56ff88",57171:"85179503",57246:"4dd4bc84",57256:"7adf996f",57338:"bdfcb8c1",57412:"7c5f254e",57506:"8b3e4221",57526:"764a4adf",57559:"69433c1a",57646:"a751f782",57748:"bd31b45c",57779:"bd395a44",57793:"9038fbaf",57890:"dbacad2f",57953:"1d6bf78f",57965:"a53ed685",58053:"94bc0e0f",58202:"c5439226",58270:"e51be0c5",58540:"455c6ba4",58662:"dbed5459",58860:"cc04598c",58867:"b8348f33",58941:"44579497",58959:"5ee1c06e",58967:"18a75ff7",59080:"56d6c64f",59104:"6490e813",59174:"4a9fe322",59359:"8dc55a26",59373:"0d93c70d",59457:"454c6390",59694:"4a11c655",59831:"b19a9981",59868:"19292318",59925:"0354d339",60155:"9cd78e06",60165:"c14392bd",60275:"eade44cc",60486:"f6c23c5a",60533:"bf6eb166",60593:"54dd1bbf",60757:"b14df74b",60849:"f571c38a",60862:"4f13a3e6",60905:"02437552",61184:"97755d31",61215:"9ab007a2",61228:"e4b844af",61242:"7e230539",61251:"a7a9c0c0",61295:"1d8eb3c2",61333:"caf12e36",61389:"a9e51a54",61465:"7f185f97",61470:"e5be67a5",61497:"904867f1",61681:"e876e0c5",61719:"139b6e1b",61794:"765e5f47",62030:"33dcbe0b",62189:"f24ad146",62276:"993a2026",62289:"218ffb26",62384:"11df8246",62489:"3c1e7e02",62520:"7c1d7b69",62524:"feaaf299",62608:"e7416c38",62888:"fbe55a66",63093:"83a9c8b0",63310:"caba2c22",63320:"013dd6ba",63554:"99caa6e0",63569:"74948dfa",63636:"eee2858a",63671:"9fa8c23d",63707:"1b70b723",63716:"072f9e9d",63758:"0e59a525",63791:"4ea7d528",63883:"e39e2c04",63906:"a1741d3d",63953:"b9a41d7f",64044:"3814e78f",64130:"711381e8",64158:"0dbd08ce",64348:"7382e722",64415:"94f564c5",64475:"497cc096",64517:"61328e38",64711:"b4b09ae2",64733:"15191a41",64792:"ff8a079d",64805:"4da6ad74",65111:"103134d2",65279:"884bf7b7",65345:"220637c1",65592:"b232c00f",65598:"9592a4bb",65608:"f00f6230",65643:"f6c969c3",65732:"427ea594",65767:"e6fe5f2e",65768:"66955f4b",65789:"3a53cfa2",65822:"c78085d1",65909:"195e2749",66147:"a9d9e09b",66181:"8ec70726",66197:"fe892181",66207:"b3c87b40",66280:"6d309f48",66373:"555e9c98",66418:"a843ff29",66464:"b986bae7",66575:"9057c318",66598:"92cfd750",66626:"6fa5c6c3",67198:"6ad2aa0e",67431:"f48723d0",67453:"18b29091",67570:"984bdc34",67751:"fe72bc7d",67784:"313b1c89",67796:"69fbb5a4",67964:"8836b877",67986:"248d36ac",68346:"f7740da1",68453:"1385e606",68498:"5aba3b5b",68677:"ec8edc56",68725:"e1664891",68750:"123d9ecb",68862:"a3b00d11",68892:"b80b7c68",69078:"9d7fd0f3",69360:"8c88f5e5",69466:"b40ab867",69550:"b54a07b5",69595:"353b19b9",69601:"f1b2f91e",69603:"56fe94f5",69775:"1125ec95",69872:"3b51da84",69890:"c06bd1f8",69958:"2b82839d",69966:"4a5d3ce2",70113:"32c880bb",70124:"66a5d682",70178:"685379d4",70195:"f0a65784",70210:"a844794a",70231:"c9ab983a",70258:"4f6b7098",70269:"981c3edc",70520:"0b9eb412",70602:"23e33787",70700:"70eeadb2",70747:"5971b4cd",70804:"1c87ee5d",70807:"b11e4ce7",70981:"83aae562",71090:"816be372",71125:"b00667b9",71392:"45266cfb",71416:"79d48d12",71598:"4d302c30",71651:"407713ec",72014:"5dd924c9",72071:"26fa81c4",72103:"1d1c8a72",72209:"67c2cb59",72290:"064e7aeb",72301:"4b03f43b",72406:"99ae91f4",72475:"e5aa0f74",72514:"ec90b7c4",72523:"00fde868",72846:"e8d214c1",72884:"3fae4551",72948:"ea3df05b",72949:"fa5d2b63",73021:"7a6529ff",73034:"e12e03ab",73038:"b18c7f51",73050:"04ed1ed2",73051:"6456d8da",73066:"d4441034",73094:"12efdc8a",73134:"861af494",73254:"0b020ed2",73272:"dd2d3db9",73282:"05a01347",73292:"eeb9bff6",73299:"c5d0185e",73318:"ff685d3f",73630:"483b5851",73679:"7229536b",73706:"f176e716",73714:"b814b661",73733:"979df0eb",73794:"028f7898",73804:"80e822c1",73813:"090443b4",73882:"272cf9fe",73919:"d417c424",73920:"2ffb7780",74085:"c3e74dbb",74111:"2b58ced5",74162:"227952a1",74188:"55510695",74291:"c46e85c2",74352:"4acd3508",74438:"8ceef940",74812:"dc8f75a8",74867:"ad3a3974",74877:"524690cd",75025:"ade7ea5f",75114:"01ff82c4",75190:"e86a4357",75452:"f83636b2",75545:"352aa1d2",75658:"bbff8fc4",75799:"80523442",75963:"881d5ad2",76297:"2158f07f",76477:"620bc63a",76492:"11201b21",76709:"72c6a25e",76724:"6711a60d",76751:"8167481a",76780:"3ad3fec4",76902:"479b5db9",76921:"88193994",76964:"2745d586",77103:"668b2761",77337:"55fc6cbc",77378:"bad7db08",77394:"9de0272b",77525:"ad14f638",77534:"ba2be641",77605:"fb26e74a",77714:"c8f65954",77813:"7a990028",77982:"e093a8b2",78055:"492b8f78",78140:"304f303f",78404:"13643c62",78442:"bca48136",78477:"f8b7b85f",78499:"22d5252a",78545:"86c5e66b",78595:"9e8742ea",78729:"7d77d735",78770:"c9d5b426",78784:"ca008628",78909:"b44f3bf7",79140:"2e615b5c",79187:"42ab8cd7",79338:"f550b3eb",79457:"c499c4c5",79458:"86114dfe",79502:"0134b282",79618:"578b9cbe",79683:"353feec5",79705:"11fa6ce8",79794:"3a579921",79871:"184aea33",79882:"516732ec",79959:"b76b6fe1",79980:"87164a66",80053:"dd8f2869",80102:"1103e64a",80180:"14e3fcac",80258:"184d68cb",80298:"67f37377",80350:"97d7f764",80352:"4d999fc3",80366:"a2467da1",80382:"78b8586f",80395:"b53911fc",80471:"ed0d866e",80481:"b29eaf9b",80597:"7149f1cf",80683:"4bd76d03",80707:"04cc300f",80742:"85bfd7e4",80757:"322d5d5e",80781:"bf6cf1f4",80784:"ded9a31f",80922:"db0b32bd",80929:"0e772bad",80957:"45e08b2a",81026:"d5d6d18c",81113:"15e596f0",81131:"44fb2c77",81147:"cf560198",81206:"db753b4e",81324:"eb84fbd7",81475:"1259d877",81500:"eb036a5a",81519:"7e74f32d",81623:"7acf5b82",81627:"38ad2086",81674:"4dd36fdb",81720:"3b4191a5",82009:"30c2c329",82048:"bf6967df",82161:"fc331579",82229:"e278917d",82247:"090cd1ea",82283:"2809c695",82384:"0f9383f3",82385:"19bb88a1",82500:"e91a3564",82724:"a553ba3c",82934:"fa7b4970",83056:"2cb69935",83058:"515c7e28",83075:"59c7cc51",83081:"dc442dde",83082:"997abd47",83100:"cde6b887",83102:"556f7467",83210:"fda69c0b",83231:"015871c9",83352:"4b25b461",83353:"d36eeeaf",83425:"fc5a37cd",83454:"90812554",83470:"77b90cea",83488:"1d0d1314",83544:"1498db6a",83651:"8d0d198d",83878:"5dadd351",83889:"a2ff1194",83969:"527a016e",83995:"83d122b0",84002:"bde9730e",84024:"c166a7a6",84093:"45833371",84146:"0844a241",84170:"f71408bd",84305:"c2280e54",84501:"9dacf513",84549:"1873b686",84585:"02a62b44",84668:"5dd7103c",84892:"729b3e0a",84936:"e62ff242",84994:"f78108ef",85098:"fcc1afb6",85158:"6117cf06",85165:"097bbf73",85498:"dbab45ab",85587:"39573440",85657:"96260064",85928:"a4c8af40",86006:"d517592c",86007:"98c7cb48",86056:"15c0b0b7",86062:"b735e4df",86079:"6a8b65ac",86080:"42b02c56",86169:"9eb9f836",86229:"30eb5ef3",86459:"45310015",86479:"65c1c405",86505:"4b7beb8d",86593:"9afea15c",86717:"3313775c",86730:"65ff6c28",86740:"26b96f23",86746:"f506bb3e",86751:"84924788",86883:"ff8236f3",86955:"f414a927",87069:"dc7a7cc3",87293:"310acc9f",87302:"e568bce3",87376:"341e57c3",87439:"46967fe7",87458:"df47c75f",87496:"2b50670f",87554:"6852a3bd",87606:"b9e932e3",87964:"5eafbaca",88055:"5c741d7a",88085:"61cf34c2",88092:"f3cf5544",88127:"ef5b8e19",88167:"c9b52319",88205:"68800bd1",88209:"64a0243f",88262:"667b764c",88438:"6d7c24ac",88445:"18aa0d43",88469:"e27db3d4",88661:"728d7340",88768:"6a651be2",88812:"948c4ba0",88823:"ee8cfa33",88990:"d622361d",89067:"09dedfba",89118:"149726e1",89147:"82bec8ff",89178:"8feec8c8",89221:"a641c2d9",89244:"d265b281",89284:"c5ed60b5",89357:"5491b86b",89383:"910fbf56",89473:"b61c2c16",89474:"0721ea92",89573:"367a5b08",89671:"4dd782b9",89730:"88be35f2",89782:"403eb6f6",89839:"51eac1ee",89938:"48e66efa",89961:"c00e806c",90129:"d553f69c",90134:"c040e7a4",90143:"0d46b9dc",90216:"08c7d6c2",90269:"b91646a1",90475:"85a75f3d",90674:"6df9699f",90802:"9569477c",91077:"dbe3e93f",91091:"d7aad258",91215:"c01b40cf",91360:"167bbbc9",91483:"414d6b9e",91565:"3e07e201",91692:"a778d712",91702:"910a0768",91743:"acd102a6",91789:"1364be6d",91859:"71d3c754",91869:"9e723314",91951:"158bdeb4",92099:"322ba068",92289:"e54ae662",92296:"0e6bfb76",92412:"a94d8851",92485:"76112eda",92528:"b21994ad",92627:"d1ec4ff0",92657:"8ccc6ea8",92778:"365f375b",92993:"4613d09b",93262:"4cdf0a8b",93369:"16114c8e",93420:"85064337",93441:"20bd2b14",93526:"28015b24",93627:"8d424660",93784:"a1f52e6c",93853:"59e45c82",93857:"3d1aacab",93865:"32c9c0b1",93889:"459a2685",93923:"7b384e9c",93927:"f55abe09",93931:"abfca5a6",94124:"b3b51880",94205:"aab9e8ff",94232:"0ed56806",94321:"1ba035df",94398:"13a0fec6",94594:"c5b629f5",94727:"78b137c8",94747:"7c14d22f",94761:"b7cc3e3c",94986:"8085cd9b",95035:"4e9e1512",95129:"1f8e282d",95163:"d2b4ad44",95215:"738c08fd",95406:"57ab0c5a",95669:"7d86bcd8",95787:"8a654fac",95836:"4e9e6cca",95924:"66594729",95932:"4ed01ebc",95986:"dafbb84b",96034:"6226761c",96203:"20494bde",96363:"e4a6eb7e",96391:"ffdf2a45",96403:"3a5c5da1",96440:"b3971c0f",96481:"92fae2ec",96540:"82fbf8e3",96543:"1638716b",96571:"8d91e091",96684:"505c7118",96687:"e87414ff",96756:"9b807ab4",96774:"f72ffcb3",96861:"f9e15cb3",96916:"0f94b704",96926:"90ac4cea",97006:"0da448cc",97180:"51ca3300",97241:"0891f07e",97310:"de1ec67f",97338:"51424d9b",97457:"8bb6adae",97462:"5605d7e3",97466:"cf16dc1a",97628:"2dc7cabf",97659:"a45fefbd",97668:"200788fe",97680:"630e8bd2",97746:"cd0435fa",97773:"2f210360",97795:"1537ed20",97807:"3935fa91",97815:"10efff8f",97920:"c95888b8",98055:"b353acdf",98211:"92c0ab9a",98224:"4768e575",98253:"e7e994a3",98285:"39c23a95",98431:"f7056ff5",98471:"126568f7",98478:"659a22f6",98488:"2d922c51",98535:"9d32530e",98566:"98a9fd57",98619:"a76beb4d",98647:"66883c80",98650:"439c1c72",98685:"a809a160",98764:"4d4c3891",98853:"699feca3",98905:"bbad7412",98906:"bf476074",98915:"bfbe7bf9",99200:"393329cd",99296:"62a2c345",99344:"0b2758c5",99354:"e1807f55",99444:"e17a6dfd",99469:"0e7e3ae5",99523:"bbd1b109",99544:"448445b1",99557:"0d4acabc",99622:"89517064",99635:"a8477af5",99669:"39bd1d43",99677:"d145929f",99802:"08339b8a",99816:"f0897d9a",99871:"8d31e216",99917:"bc60a436",99969:"ddde681d",99988:"1f182e3b"}[e]+".js"},n.miniCssF=function(e){},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(e){if("object"==typeof window)return window}}(),n.o=function(e,f){return Object.prototype.hasOwnProperty.call(e,f)},b={},d="rancher-docs:",n.l=function(e,f,c,a){if(b[e])b[e].push(f);else{var t,r;if(void 0!==c)for(var o=document.getElementsByTagName("script"),u=0;u Backup and Restore for Rancher Installed with Docker | Rancher Manager - +
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/cluster-provisioning/rke-clusters/options.html b/cluster-provisioning/rke-clusters/options.html index 0d70684b24b..dbc322291b3 100644 --- a/cluster-provisioning/rke-clusters/options.html +++ b/cluster-provisioning/rke-clusters/options.html @@ -5,13 +5,13 @@ RKE Cluster Configuration | Rancher Manager - +
Version: v2.6

RKE Cluster Configuration

This page has moved here.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/contribute-to-rancher.html b/contribute-to-rancher.html index 0f215ab6437..cb7a90128b8 100644 --- a/contribute-to-rancher.html +++ b/contribute-to-rancher.html @@ -5,13 +5,13 @@ Contributing to Rancher | Rancher Manager - +
Version: v2.6

Contributing to Rancher

This section explains the repositories used for Rancher, how to build the repositories, and what information to include when you file an issue.

For more detailed information on how to contribute to the development of Rancher projects, refer to the Rancher Developer Wiki. The wiki has resources on many topics, including the following:

  • How to set up the Rancher development environment and run tests
  • The typical flow of an issue through the development lifecycle
  • Coding guidelines and development best practices
  • Debugging and troubleshooting
  • Developing the Rancher API

On the Rancher Users Slack, the channel for developers is #developer.

Repositories​

All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher.

RepositoryURLDescription
Rancherhttps://github.com/rancher/rancherThis repository is the main source code for Rancher 2.x.
Typeshttps://github.com/rancher/typesThis repository is the repository that has all the API types for Rancher 2.x.
API Frameworkhttps://github.com/rancher/normanThis repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources.
User Interfacehttps://github.com/rancher/dashboard/This repository is the source of the Dashboard UI.
(Rancher) Docker Machinehttps://github.com/rancher/machineThis repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the docker/machine repository.
machine-packagehttps://github.com/rancher/machine-packageThis repository is used to build the Rancher Docker Machine binary.
kontainer-enginehttps://github.com/rancher/kontainer-engineThis repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters.
RKE repositoryhttps://github.com/rancher/rkeThis repository is the source of Rancher Kubernetes Engine, the tool to provision Kubernetes clusters on any machine.
CLIhttps://github.com/rancher/cliThis repository is the source code for the Rancher CLI used in Rancher 2.x.
(Rancher) Helm repositoryhttps://github.com/rancher/helmThis repository is the source of the packaged Helm binary. This is a fork of the helm/helm repository.
Telemetry repositoryhttps://github.com/rancher/telemetryThis repository is the source for the Telemetry binary.
loglevel repositoryhttps://github.com/rancher/loglevelThis repository is the source of the loglevel binary, used to dynamically change log levels.

To see all libraries/projects used in Rancher, see the go.mod file in the rancher/rancher repository.

Rancher diagram

Rancher components used for provisioning/managing Kubernetes clusters.

Building​

Every repository should have a Makefile and can be built using the make command. The make targets are based on the scripts in the /scripts directory in the repository, and each target will use Dapper to run the target in an isolated environment. The Dockerfile.dapper will be used for this process, and includes all the necessary build tooling needed.

The default target is ci, and will run ./scripts/validate, ./scripts/build, ./scripts/test and ./scripts/package. The resulting binaries of the build will be in ./build/bin and are usually also packaged in a Docker image.

Bugs, Issues or Questions​

If you find any bugs or are having any trouble, please search the reported issue as someone may have experienced the same issue or we are actively working on a solution.

If you can't find anything related to your issue, contact us by filing an issue. Though we have many repositories related to Rancher, we want the bugs filed in the Rancher repository so we won't miss them! If you want to ask a question or ask fellow users about an use case, we suggest creating a post on the Rancher Forums.

Checklist for Filing Issues​

Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue.

note

For large amounts of data, please use GitHub Gist or similar and link the created resource in the issue.

Important:

Please remove any sensitive data as it will be publicly viewable.

  • Resources: Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below:

    • Hosts: What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce
    • Operating System: What operating system are you using? Providing specifics helps here like the output of cat /etc/os-release for exact OS release and uname -r for exact kernel used
    • Docker: What Docker version are you using, how did you install it? Most of the details of Docker can be found by supplying output of docker version and docker info
    • Environment: Are you in a proxy environment, are you using recognized CA/self signed certificates, are you using an external loadbalancer
    • Rancher: What version of Rancher are you using, this can be found on the bottom left of the UI or be retrieved from the image tag you are running on the host
    • Clusters: What kind of cluster did you create, how did you create it, what did you specify when you were creating it

  • Steps to reproduce the issue: Provide as much detail on how you got into the reported situation. This helps the person to reproduce the situation you are in.

    • Provide manual steps or automation scripts used to get from a newly created setup to the situation you reported.

  • Logs: Provide data/logs from the used resources.

    • Rancher

      • Docker install

        docker logs \
        --timestamps \
        $(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }')

      • Kubernetes install using kubectl

        note

        Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

        kubectl -n cattle-system \
        logs \
        -l app=rancher \
        --timestamps=true

      • Docker install using docker on each of the nodes in the RKE cluster

        docker logs \
        --timestamps \
        $(docker ps | grep -E "rancher/rancher@|rancher_rancher" | awk '{ print $1 }')

      • Kubernetes Install with RKE Add-On

        note

        Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

        kubectl -n cattle-system \
        logs \
        --timestamps=true \
        -f $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name="cattle-server") | .metadata.name')

    • System logging (these might not all exist, depending on operating system)

      • /var/log/messages
      • /var/log/syslog
      • /var/log/kern.log

    • Docker daemon logging (these might not all exist, depending on operating system)

      • /var/log/docker.log

  • Metrics: If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of top, free -m, df which shows processes/memory/disk usage.

Docs​

If you have any updates to our documentation, please make any pull request to our docs repo.

  • Rancher 2.x Docs repository: This repo is where all the docs for Rancher 2.x are located. They are located in the content folder in the repo.

  • Rancher 1.x Docs repository: This repo is where all the docs for Rancher 1.x are located. They are located in the rancher folder in the repo.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations.html b/explanations.html index 757c419d912..37332d6cf4c 100644 --- a/explanations.html +++ b/explanations.html @@ -5,13 +5,13 @@ Explanations | Rancher Manager - +
Version: v2.6

Explanations

Explanatory docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cis-scans/configuration-reference.html b/explanations/integrations-in-rancher/cis-scans/configuration-reference.html index 9da881ea627..d735b070b3b 100644 --- a/explanations/integrations-in-rancher/cis-scans/configuration-reference.html +++ b/explanations/integrations-in-rancher/cis-scans/configuration-reference.html @@ -5,13 +5,13 @@ Configuration | Rancher Manager - +
Version: v2.6

Configuration

This configuration reference is intended to help you manage the custom resources created by the rancher-cis-benchmark application. These resources are used for performing CIS scans on a cluster, skipping tests, setting the test profile that will be used during a scan, and other customization.

To configure the custom resources, go to the Cluster Dashboard To configure the CIS scans,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to configure CIS scans and click Explore.
  3. In the left navigation bar, click CIS Benchmark.

Scans​

A scan is created to trigger a CIS scan on the cluster based on the defined profile. A report is created after the scan is completed.

When configuring a scan, you need to define the name of the scan profile that will be used with the scanProfileName directive.

An example ClusterScan custom resource is below:

apiVersion: cis.cattle.io/v1
kind: ClusterScan
metadata:
  name: rke-cis
spec:
  scanProfileName: rke-profile-hardened

Profiles​

A profile contains the configuration for the CIS scan, which includes the benchmark version to use and any specific tests to skip in that benchmark.

caution

By default, a few ClusterScanProfiles are installed as part of the rancher-cis-benchmark chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles.

Users can clone the ClusterScanProfiles to create custom profiles.

Skipped tests are listed under the skipTests directive.

When you create a new profile, you will also need to give it a name.

An example ClusterScanProfile is below:

apiVersion: cis.cattle.io/v1
kind: ClusterScanProfile
metadata:
  annotations:
    meta.helm.sh/release-name: clusterscan-operator
    meta.helm.sh/release-namespace: cis-operator-system
  labels:
    app.kubernetes.io/managed-by: Helm
  name: "<example-profile>"
spec:
  benchmarkVersion: cis-1.5
  skipTests:
    - "1.1.20"
    - "1.1.21"

Benchmark Versions​

A benchmark version is the name of benchmark to run using kube-bench, as well as the valid configuration parameters for that benchmark.

A ClusterScanBenchmark defines the CIS BenchmarkVersion name and test configurations. The BenchmarkVersion name is a parameter provided to the kube-bench tool.

By default, a few BenchmarkVersion names and test configurations are packaged as part of the CIS scan application. When this feature is enabled, these default BenchmarkVersions will be automatically installed and available for users to create a ClusterScanProfile.

caution

If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks.

A ClusterScanBenchmark consists of the fields:

  • ClusterProvider: This is the cluster provider name for which this benchmark is applicable. For example: RKE, EKS, GKE, etc. Leave it empty if this benchmark can be run on any cluster type.
  • MinKubernetesVersion: Specifies the cluster's minimum kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular Kubernetes version.
  • MaxKubernetesVersion: Specifies the cluster's maximum Kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular k8s version.

An example ClusterScanBenchmark is below:

apiVersion: cis.cattle.io/v1
kind: ClusterScanBenchmark
metadata:
  annotations:
    meta.helm.sh/release-name: clusterscan-operator
    meta.helm.sh/release-namespace: cis-operator-system
  creationTimestamp: "2020-08-28T18:18:07Z"
  generation: 1
  labels:
    app.kubernetes.io/managed-by: Helm
  name: cis-1.5
  resourceVersion: "203878"
  selfLink: /apis/cis.cattle.io/v1/clusterscanbenchmarks/cis-1.5
  uid: 309e543e-9102-4091-be91-08d7af7fb7a7
spec:
  clusterProvider: ""
  minKubernetesVersion: 1.15.0
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html b/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html index d3a6485e70f..c6deb3acc74 100644 --- a/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html +++ b/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html @@ -5,14 +5,14 @@ Creating a Custom Benchmark Version for Running a Cluster Scan | Rancher Manager - +
Version: v2.6

Creating a Custom Benchmark Version for Running a Cluster Scan

Each Benchmark Version defines a set of test configuration files that define the CIS tests to be run by the kube-bench tool. The rancher-cis-benchmark application installs a few default Benchmark Versions which are listed under CIS Benchmark application menu.

But there could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.

It is now possible to create a custom Benchmark Version for running a cluster scan using the rancher-cis-benchmark application.

When a cluster scan is run, you need to select a Profile which points to a specific Benchmark Version.

Follow all the steps below to add a custom Benchmark Version and run a scan using it.

1. Prepare the Custom Benchmark Version ConfigMap​

To create a custom benchmark version, first you need to create a ConfigMap containing the benchmark version's config files and upload it to your Kubernetes cluster where you want to run the scan.

To prepare a custom benchmark version ConfigMap, suppose we want to add a custom Benchmark Version named foo.

  1. Create a directory named foo and inside this directory, place all the config YAML files that the kube-bench tool looks for. For example, here are the config YAML files for a Generic CIS 1.5 Benchmark Version https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5

  2. Place the complete config.yaml file, which includes all the components that should be tested.

  3. Add the Benchmark version name to the target_mapping section of the config.yaml:

    target_mapping:
      "foo":
        - "master"
        - "node"
        - "controlplane"
        - "etcd"
        - "policies"

  4. Upload this directory to your Kubernetes Cluster by creating a ConfigMap:

    kubectl create configmap -n <namespace> foo --from-file=<path to directory foo>

2. Add a Custom Benchmark Version to a Cluster​

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to add a custom benchmark and click Explore.
  3. In the left navigation bar, click CIS Benchmark > Benchmark Version.
  4. Click Create.
  5. Enter the Name and a description for your custom benchmark version.
  6. Choose the cluster provider that your benchmark version applies to.
  7. Choose the ConfigMap you have uploaded from the dropdown.
  8. Add the minimum and maximum Kubernetes version limits applicable, if any.
  9. Click Create.

3. Create a New Profile for the Custom Benchmark Version​

To run a scan using your custom benchmark version, you need to add a new Profile pointing to this benchmark version.

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to add a custom benchmark and click Explore.
  3. In the left navigation bar, click CIS Benchmark > Profile.
  4. Click Create.
  5. Provide a Name and description. In this example, we name it foo-profile.
  6. Choose the Benchmark Version from the dropdown.
  7. Click Create.

4. Run a Scan Using the Custom Benchmark Version​

Once the Profile pointing to your custom benchmark version foo has been created, you can create a new Scan to run the custom test configs in the Benchmark Version.

To run a scan,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to add a custom benchmark and click Explore.
  3. In the left navigation bar, click CIS Benchmark > Scan.
  4. Click Create.
  5. Choose the new cluster scan profile.
  6. Click Create.

Result: A report is generated with the scan results. To see the results, click the name of the scan that appears.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html b/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html index 173c4738fe8..36c144c3eb5 100644 --- a/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html +++ b/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html @@ -5,7 +5,7 @@ Roles-based Access Control | Rancher Manager - + @@ -15,7 +15,7 @@ Rancher v2.5.2 because it essentially is same as cis-admin. If you for cis-edit, please update them to use cis-admin ClusterRole instead.

Cluster-Admin Access​

Rancher CIS Scans is a cluster-admin only feature by default. This means only the Rancher global admins, and the cluster’s cluster-owner can:

  • Install/Uninstall the rancher-cis-benchmark App
  • See the navigation links for CIS Benchmark CRDs - ClusterScanBenchmarks, ClusterScanProfiles, ClusterScans
  • List the default ClusterScanBenchmarks and ClusterScanProfiles
  • Create/Edit/Delete new ClusterScanProfiles
  • Create/Edit/Delete a new ClusterScan to run the CIS scan on the cluster
  • View and Download the ClusterScanReport created after the ClusterScan is complete

Summary of Default Permissions for Kubernetes Default Roles​

The rancher-cis-benchmark creates three ClusterRoles and adds the CIS Benchmark CRD access to the following default K8s ClusterRoles:

ClusterRole created by chartDefault K8s ClusterRolePermissions given with Role
cis-adminadminAbility to CRUD clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR
cis-viewview Ability to List(R) clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR

By default only cluster-owner role will have ability to manage and use rancher-cis-benchmark feature.

The other Rancher roles (cluster-member, project-owner, project-member) do not have any default permissions to manage and use rancher-cis-benchmark resources.

But if a cluster-owner wants to delegate access to other users, they can do so by creating ClusterRoleBindings between these users and the above CIS ClusterRoles manually. There is no automatic role aggregation supported for the rancher-cis-benchmark ClusterRoles.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html b/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html index 10f1dc9cfff..467408377ee 100644 --- a/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html +++ b/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html @@ -5,13 +5,13 @@ Skipped and Not Applicable Tests | Rancher Manager - +
Version: v2.6

Skipped and Not Applicable Tests

This section lists the tests that are skipped in the permissive test profile for RKE.

All the tests that are skipped and not applicable on this page will be counted as Not Applicable in the v2.5 generated report. The skipped test count will only mention the user-defined skipped tests. This allows user-skipped tests to be distinguished from the tests that are skipped by default in the RKE permissive test profile.

CIS Benchmark v1.5​

CIS Benchmark v1.5 Skipped Tests​

NumberDescriptionReason for Skipping
1.1.12Ensure that the etcd data directory ownership is set to etcd:etcd (Automated)A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership.
1.2.6Ensure that the --kubelet-certificate-authority argument is set as appropriate (Automated)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
1.2.16Ensure that the admission control plugin PodSecurityPolicy is set (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
1.2.33Ensure that the --encryption-provider-config argument is set as appropriate (Manual)Enabling encryption changes how data can be recovered as data is encrypted.
1.2.34Ensure that encryption providers are appropriately configured (Manual)Enabling encryption changes how data can be recovered as data is encrypted.
4.2.6Ensure that the --protect-kernel-defaults argument is set to true (Automated)System level configurations are required before provisioning the cluster in order for this argument to be set to true.
4.2.10Ensure that the--tls-cert-file and --tls-private-key-file arguments are set as appropriate (Automated)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
5.1.5Ensure that default service accounts are not actively used. (Automated)Kubernetes provides default service accounts to be used.
5.2.2Minimize the admission of containers wishing to share the host process ID namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
5.2.3Minimize the admission of containers wishing to share the host IPC namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
5.2.4Minimize the admission of containers wishing to share the host network namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
5.2.5Minimize the admission of containers with allowPrivilegeEscalation (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
5.3.2Ensure that all Namespaces have Network Policies defined (Automated)Enabling Network Policies can prevent certain applications from communicating with each other.
5.6.4The default namespace should not be used (Automated)Kubernetes provides a default namespace.

CIS Benchmark v1.5 Not Applicable Tests​

NumberDescriptionReason for being not applicable
1.1.1Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
1.1.2Ensure that the API server pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
1.1.3Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
1.1.4Ensure that the controller manager pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
1.1.5Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
1.1.6Ensure that the scheduler pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
1.1.7Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
1.1.8Ensure that the etcd pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
1.1.13Ensure that the admin.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
1.1.14Ensure that the admin.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
1.1.15Ensure that the scheduler.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
1.1.16Ensure that the scheduler.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
1.1.17Ensure that the controller-manager.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
1.1.18Ensure that the controller-manager.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
1.3.6Ensure that the RotateKubeletServerCertificate argument is set to true (Automated)Clusters provisioned by RKE handles certificate rotation directly through RKE.
4.1.1Ensure that the kubelet service file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
4.1.2Ensure that the kubelet service file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
4.1.9Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
4.1.10Ensure that the kubelet configuration file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
4.2.12Ensure that the RotateKubeletServerCertificate argument is set to true (Automated)Clusters provisioned by RKE handles certificate rotation directly through RKE.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.html b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.html index 2940badab8c..7a8956d965b 100644 --- a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.html +++ b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/adapter-requirements.html @@ -5,7 +5,7 @@ Prerequisites | Rancher Manager - + @@ -13,7 +13,7 @@
Version: v2.6

Prerequisites

1. Setting Up License Manager and Purchasing Support​

First, complete the first step of the license manager one-time setup. Next, go to the AWS Marketplace. Locate the "Rancher Premium Support Billing Container Starter Pack". Purchase at least one entitlement.

If you have installed Rancher using the "Rancher Setup" AWS Marketplace offering, skip to Step 4.

Note: Each entitlement grants access to support for a certain amount of nodes. You can purchase more licenses as necessary later on.

2. Create an EKS Cluster​

Follow the Rancher docs to create an EKS cluster. When you get to the final step to install Rancher, stop and return to this page. This cluster will need to meet the following requirements:

  • EKS version 1.22.
  • Each node in the cluster has access to the registry containing Rancher and its related images.
  • Each node in the cluster has access to the ECR repo storing the CSP Adapter.
  • Each node in the cluster has access to the license manager service.
  • Each node in the cluster has access to global endpoints for the STS service.

3. Install Rancher​

In addition to the options specified to install Rancher in the Rancher docs, you will also need to enable extra metrics. This can be done through the Helm CLI through the following options:

--set extraEnv\[0\].name="CATTLE_PROMETHEUS_METRICS" --set-string extraEnv\[0\].value=true

You can also use a values.yaml like the below:

extraEnv:
  - name: "CATTLE_PROMETHEUS_METRICS"
    value: "true"

You will also need to install Rancher version 2.6.7 or higher.

4. Create an OIDC Provider​

Follow the AWS documentation to create an OIDC provider for the cluster specified in the previous section.

5. Create an IAM Role​

An IAM role is required for the CSP adapter to check-in/check-out entitlements.

First, configure the trust policy as below. Replace MY_AWS_ACC with your AWS account number, MY_AWS_REGION with your AWS region, and MY_OIDC_PROVIDER with the id of your OIDC provider:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::${MY_AWS_ACC}:oidc-provider/oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:sub": "system:serviceaccount:cattle-csp-adapter-system:rancher-csp-adapter",
                    "oidc.eks.${MY_AWS_REGION}.amazonaws.com/id/${MY_OIDC_PROVIDER}:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Next, use a policy for the role which has the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RancherCSPAdapterPermissions",
            "Effect": "Allow",
            "Action": [
                "license-manager:ListReceivedLicenses",
                "license-manager:CheckoutLicense",
                "license-manager:ExtendLicenseConsumption",
                "license-manager:CheckInLicense",
                "license-manager:GetLicense",
                "license-manager:GetLicenseUsage"
            ],
            "Resource": "*"
        }
    ]
}

Save the name of the role. You will need it later on when installing the CSP adapter.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.html b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.html index 5a3101c82c4..9024ab1fd9d 100644 --- a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.html +++ b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/common-issues.html @@ -5,13 +5,13 @@ Common Issues | Rancher Manager - +
Version: v2.6

Common Issues

After installing the adapter, a banner message appears in Rancher that says "AWS Marketplace Adapter: Unable to run the adapter, please check the adapter logs"

This error indicates that while the adapter was installed into the cluster, an error has occurred which prevents it from properly checking-in/checking-out licenses.

This often occurs because the IAM role was not set up properly. Review the prerequisites and verify that:

  • An OIDC provider has been created/associated with the cluster Rancher is running on.
  • The IAM role has been configured to trust this OIDC provider.
  • The IAM role has at least the permissions outlined in the policy.

If all of the above have been configured correctly, reach out to support for assistance.

I see a banner message that states, "AWS Marketplace Adapter: You have exceeded your licensed node count. At least x more license(s) are required in AWS to become compliant"

This message indicates that you do not have enough entitlements for the amount of nodes Rancher is currently managing.

Keep in mind the following limitations:

  • Each entitlement is valid for a certain number of nodes.
  • Every node currently managed by Rancher counts toward your usage total (with exception of nodes in the cluster rancher is installed on).
  • Each entitlement can be used by at most one Rancher instance. For example, if you have two running Rancher instances in your account (each installed on a separate EKS cluster), then you will need at least two entitlements.

You may also have recently uninstalled/re-installed the adapter. If the adapter loses track of the licenses that it is currently managing, it can take up to an hour to resolve the actual state of the licenses.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.html b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.html index ebc1bff3f43..7799ddce2fd 100644 --- a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.html +++ b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.html @@ -5,14 +5,14 @@ Installing the Adapter | Rancher Manager - +
Version: v2.6

Installing the Adapter

Important: If you are attempting to re-install the adapter, you may experience errant out-of-compliance messages for up to an hour.

Rancher vs. Adapter Compatibility Matrix​

Important:

Different versions of the CSP adapter rely on features found in specific versions of Rancher. In order to deploy and run the adapter successfully, you need to ensure its version corresponds to the necessary version of Rancher.

Rancher VersionAdapter Version
v2.6.7v1.0.1
v2.6.8v1.0.1

1. Gain Access to the Local Cluster​

Note: Only admin users should have access to the local cluster. Because the CSP adapter must be installed in the local cluster, this installation must be carried out by an admin user.

First, click on the local cluster and download a kubeconfig token. You can then configure your CLI to use this new token with the following command, replacing $TOKEN_PATH with the path on your filesystem to the downloaded token:

export KUBECONFIG=$TOKEN_PATH

2. Create the Adapter Namespace​

Create the namespace that the adapter will be installed in.

kubectl create ns cattle-csp-adapter-system

3. Create Certificate Secrets​

The adapter requires access to the root CA that Rancher is using to communicate with the Rancher server. You can read more about which certificate options Rancher supports in the chart options page.

If your Rancher install uses a certificate signed by a recognized Certificate Authority such as Let's Encrypt, then you can safely skip to Step 4.

However, if your Rancher install uses a custom certificate such as a Rancher-generated certificate or one signed by a private Certificate Authority, you will need to provide the certificate for this authority in PEM-encoded format so that the adapter can communicate with Rancher.

First, retrieve the certificate that Rancher is using and place in a file named ca-additional.pem. If you are using the Rancher-generated certs option, this can be done with the following command:

kubectl get secret tls-rancher -n cattle-system -o jsonpath="{.data.tls\.crt}" | base64 -d  >> ca-additional.pem

Then, create a secret which uses this cert:

kubectl -n cattle-csp-adapter-system create secret generic tls-ca-additional --from-file=ca-additional.pem

Important: Do not change the names of the file or of the created secret. Making changes to these values may result in errors when the adapter runs.

4. Install the Chart​

First, add the rancher/charts repo using the following command:

helm repo add rancher-charts https://charts.rancher.io

Next, install the CSP adapter. You must specify several values, including the account number, and the name of the role created in the prerequisites.

For the below instructions, replace $MY_ACC_NUM with your AWS account number and $MY_ROLE_NAME with the name of the role created in the prerequisites.

Note: If you use shell variables, do not specify quotation marks. For example, MY_ACC_NUM=123456789012 will work, but MY_ACC_NUM="123456789012" will fail.

Note: Accounts using the AWS Marketplace listing for the EU and the UK will need to specify an additional --set image.repository=rancher/rancher-csp-adapter-eu option. To see if your account needs this option when installing the adapter, refer to the usage instructions of the marketplace listing.

Note: It is important that you follow the instructions below exactly. In particular, the command to install version 1.0.1 of the adapter (by using --set image.tag=v1.0.1) is key to ensure that node counts are accurate.

helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter --namespace cattle-csp-adapter-system --set aws.enabled=true --set aws.roleName=$MY_ROLE_NAME --set-string aws.accountNumber=$MY_ACC_NUM --set image.tag=v1.0.1

Alternatively, you can use a values.yaml and specify options like below:

image:
tag: v1.0.1
aws:
enabled: true
accountNumber: "$MY_ACC_NUM"
roleName: $MY_ROLE_NAME

Note: The account number needs to be specified in a string format, like the above, or the installation will fail.

You can then install the adapter with the following command:

helm install rancher-csp-adapter rancher-charts/rancher-csp-adapter -f values.yaml

5. Managing Certificate Updates​

If you had to create a secret storing a custom cert in Step 3, you will need to update this secret over time as the certificate is rotated.

First, delete the original secret in the cattle-csp-adapter-system namespace, using the below command:

kubectl delete secret tls-ca-additional -n cattle-csp-adapter-system

Then, follow the original installation steps in Step 3 to replace the content of the secret with the updated value.

Finally, restart the rancher-csp-adapter deployment to ensure that the updated value is made available to the adapter:

kubectl rollout restart deploy rancher-csp-adapter -n cattle-csp-adapter-system

Note: There are methods such as cert-manager's trust operator which can help reduce the number of manual rotation tasks over time. While these options are not officially supported, they may be useful to users wishing to automate some of these tasks.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.html b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.html index 114c6a5c623..64df687be51 100644 --- a/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.html +++ b/explanations/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/uninstall-adapter.html @@ -5,13 +5,13 @@ Uninstalling The Adapter | Rancher Manager - +
Version: v2.6

Uninstalling The Adapter

1. Uninstall the adapter chart using helm.​

helm uninstall rancher-csp-adapter -n cattle-csp-adapter-system

2. Remove the namespace created for the adapter.​

kubectl delete ns cattle-csp-adapter-system

3. (Optional) remove any outstanding user notifications.​

kubectl delete RancherUserNotification csp-compliance
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/cloud-marketplace/supportconfig.html b/explanations/integrations-in-rancher/cloud-marketplace/supportconfig.html index bac95670957..1a58915bfb5 100644 --- a/explanations/integrations-in-rancher/cloud-marketplace/supportconfig.html +++ b/explanations/integrations-in-rancher/cloud-marketplace/supportconfig.html @@ -5,13 +5,13 @@ Supportconfig bundle | Rancher Manager - +
Version: v2.6

Supportconfig bundle

After installing the CSP adapter, you will have the ability to generate a supportconfig bundle. This bundle is a tar file which can be used to quickly provide information to support.

These bundles can be created through Rancher or through direct access to the cluster that Rancher is installed on. Note that accessing through Rancher is preferred.

Note: Only admin users can generate/download supportconfig bundles, regardless of method.

Accessing through Rancher​

First, click on the hamburger menu. Then click the Get Support button.

Get Support

In the next page, click on the Generate Support Config button.

Note: If the adapter is not installed, the option to generate the supportconfig bundle will not be present. You must install the CSP adapter to generate a supportconfig bundle.

Get Support

Accessing without rancher​

First, generate a kubeconfig for the cluster that Rancher is installed on.

Note: If Rancher is down, you will not be able to use a kubeconfig token generated by Rancher to access the cluster.

Configure your shell environment to use this kubeconfig token:

export KUBECONFIG=$MY_KUBECONFIG_PATH

It is recommended to create a temporary working directory while running this command, like below:

mkdir temp && cd temp

Then, retrieve the supportconfig bundle:

mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && tar -c -f supportconfig_rancher.tar rancher && rm -rf rancher

This will create a supportconfig_rancher.tar file in your current directory.

Users who run these commands on Mac may experience issues due to incompatibilities between gnu-tar and bsd-tar. If support has issues reading a supportconfig that you produce, try using the below command after making gnu-tar accessible as gtar on your path:

mkdir rancher && kubectl get configmap csp-config -n cattle-csp-adapter-system -o=jsonpath='{.data.data}' >> rancher/config.json && gtar -c -f supportconfig_rancher.tar rancher && rm -rf rancher
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html b/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html index 63caf2389b0..5fc26ed639f 100644 --- a/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html +++ b/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
Version: v2.6

Architecture

Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, or Kustomize or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy everything in the cluster. This gives you a high degree of control, consistency, and auditability. Fleet focuses not only on the ability to scale, but to give one a high degree of control and visibility to exactly what is installed on the cluster.

Architecture

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html b/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html index c7418c014e3..29c1eecf0fe 100644 --- a/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html +++ b/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html @@ -5,13 +5,13 @@ Using Fleet Behind a Proxy | Rancher Manager - +
Version: v2.6

Using Fleet Behind a Proxy

In this section, you'll learn how to enable Fleet in a setup that has a Rancher server with a public IP a Kubernetes cluster that has no public IP, but is configured to use a proxy.

Rancher does not establish connections with registered downstream clusters. The Rancher agent deployed on the downstream cluster must be able to establish the connection with Rancher.

To set up Fleet to work behind a proxy, you will need to set the Agent Environment Variables for the downstream cluster. These are cluster-level configuration options.

Through the Rancher UI, you can configure these environment variables for any cluster type, including registered and custom clusters. The variables can be added while editing an existing cluster or while provisioning a new cluster.

For public downstream clusters, it is sufficient to set the required environment variables in the Rancher UI.

For private nodes or private clusters, the environment variables need to be set on the nodes themselves. Then the environment variables are configured from the Rancher UI, typically when provisioning a custom cluster or when registering the private cluster. For an example of how to set the environment variables on Ubuntu node in a K3s Kubernetes cluster, see this section.

Required Environment Variables

When adding Fleet agent environment variables for the proxy, replace <PROXY_IP> with your private proxy IP.

Variable NameValue
HTTP_PROXYhttp://<PROXY_IP>:8888
HTTPS_PROXYhttp://<PROXY_IP>:8888
NO_PROXY127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local

Setting Environment Variables in the Rancher UI​

To add the environment variable to an existing cluster,

  1. Click ☰ > Cluster Management.
  2. Go to the cluster where you want to add environment variables and click ⋮ > Edit Config.
  3. Click Advanced Options.
  4. Click Add Environment Variable.
  5. Enter the required environment variables
  6. Click Save.

Result: The Fleet agent works behind a proxy.

Setting Environment Variables on Private Nodes​

For private nodes and private clusters, the proxy environment variables need to be set on the nodes themselves, as well as configured from the Rancher UI.

This example shows how the environment variables would be set up on an Ubuntu node in a K3s Kubernetes cluster:

ssh -o ForwardAgent=yes ubuntu@<public_proxy_ip>
ssh <k3s_ip>
export proxy_private_ip=<private_proxy_ip>
export HTTP_PROXY=http://${proxy_private_ip}:8888
export HTTPS_PROXY=http://${proxy_private_ip}:8888
export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html b/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html index fdc8bed9e8d..aba7ab9f1cf 100644 --- a/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html +++ b/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html @@ -5,13 +5,13 @@ Windows Support | Rancher Manager - +
Version: v2.6

Windows Support

Prior to Rancher v2.5.6, the agent did not have native Windows manifests on downstream clusters with Windows nodes. This would result in a failing agent pod for the cluster.

If you are upgrading from an older version of Rancher to v2.5.6+, you can deploy a working agent with the following workflow in the downstream cluster:

  1. Cordon all Windows nodes.
  2. Apply the below toleration to the agent workload.
  3. Uncordon all Windows nodes.
  4. Delete all agent pods. New pods should be created with the new toleration.
  5. Once the agent pods are running, and auto-update is enabled for Fleet, they should be updated to a Windows-compatible agent version.
tolerations:
- effect: NoSchedule
  key: cattle.io/os
  operator: Equal
  value: linux
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/harvester.html b/explanations/integrations-in-rancher/harvester.html index b10a67a9175..3f3b59c9ea1 100644 --- a/explanations/integrations-in-rancher/harvester.html +++ b/explanations/integrations-in-rancher/harvester.html @@ -5,13 +5,13 @@ Harvester Integration | Rancher Manager - +
Version: v2.6

Harvester Integration

Introduced in Rancher v2.6.1, Harvester is an open-source hyper-converged infrastructure (HCI) software built on Kubernetes. Harvester installs on bare metal servers and provides integrated virtualization and distributed storage capabilities. Although Harvester operates using Kubernetes, it does not require users to know Kubernetes concepts, making it a more user-friendly application.

New in v2.6.3

Harvester is GA. Please refer to the Harvester release notes for all updates.

Feature Flag​

The Harvester feature flag is used to manage access to the Virtualization Management (VM) page in Rancher where users can navigate directly to Harvester clusters and access the Harvester UI. The Harvester feature flag is enabled by default. Click here for more information on feature flags in Rancher.

To navigate to the Harvester cluster, click ☰ > Virtualization Management. From Harvester Clusters page, click one of the clusters listed to go to the single Harvester cluster view.

  • If the Harvester feature flag is enabled, Harvester clusters will be filtered out from any pages or apps (such as Fleet and the multi-cluster app) that list Kubernetes clusters.

  • If the Harvester feature flag is disabled, and a Harvester cluster is imported, the Harvester cluster will be shown in the Rancher cluster list in the Cluster Management page. Harvester clusters will only be shown on the cluster list when the feature flag is off.

  • With the Harvester integration, Harvester clusters can now be imported into Rancher as a cluster type Harvester.

  • Users may import a Harvester cluster only on the Virtualization Management page. Importing a cluster on the Cluster Management page is not supported, and a warning will advise you to return to the VM page to do so.

Harvester Node Driver​

The Harvester node driver is marked as tech preview on RKE and RKE2 options in Rancher. This will be the case both on the Create page and once the driver is already enabled. The node driver is available whether or not the Harvester feature flag is enabled. Note that the node driver is off by default. Users may create RKE or RKE2 clusters on Harvester only from the Cluster Management page.

Harvester allows .ISO images to be uploaded and displayed through the Harvester UI, but this is not supported in the Rancher UI. This is because .ISO images usually require additional setup that interferes with a clean deployment (without requiring user intervention), and they are not typically used in cloud environments.

Click here for more information on node drivers in Rancher.

Limitations​

Applicable to Rancher v2.6.1 and v2.6.2 only:

  • Harvester v0.3.0 doesn’t support air-gapped environment installation.
  • Harvester v0.3.0 doesn’t support upgrade from v0.2.0 nor upgrade to v1.0.0.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html b/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html index cb10b75a25d..07c12f2fe24 100644 --- a/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html +++ b/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html @@ -5,13 +5,13 @@ Additional Steps for Installing Istio on an RKE2 Cluster | Rancher Manager - +
Version: v2.6

Additional Steps for Installing Istio on an RKE2 Cluster

When installing or upgrading the Istio Helm chart through Apps & Marketplace,

  1. If you are installing the chart, click Customize Helm options before install and click Next.

  2. You will see options for configuring the Istio Helm chart. On the Components tab, check the box next to Enabled CNI.

  3. Add a custom overlay file specifying cniBinDir and cniConfDir. For more information on these options, refer to the Istio documentation. An example is below:

    apiVersion: install.istio.io/v1alpha1
    kind: IstioOperator
    spec:
      components:
        cni:
          enabled: true
          k8s:
            overlays:
            - apiVersion: "apps/v1"
              kind: "DaemonSet"
              name: "istio-cni-node"
              patches:
              - path: spec.template.spec.containers.[name:install-cni].securityContext.privileged
                value: true
      values:
        cni:
          image: rancher/mirrored-istio-install-cni:1.9.3
          excludeNamespaces:
            - istio-system
            - kube-system
          logLevel: info
          cniBinDir: /opt/cni/bin
          cniConfDir: /etc/cni/net.d

Result: Now you should be able to utilize Istio as desired, including sidecar injection and monitoring via Kiali.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html b/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html index 1c4d094a08e..1b0ce37c6a5 100644 --- a/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html +++ b/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html @@ -5,13 +5,13 @@ Enable Istio with Pod Security Policies | Rancher Manager - +
Version: v2.6

Enable Istio with Pod Security Policies

If you have restrictive Pod Security Policies enabled, then Istio may not be able to function correctly, because it needs certain permissions in order to install itself and manage pod infrastructure. In this section, we will configure a cluster with PSPs enabled for an Istio install, and also set up the Istio CNI plugin.

The Istio CNI plugin removes the need for each application pod to have a privileged NET_ADMIN container. For further information, see the Istio CNI Plugin docs. Please note that the Istio CNI Plugin is in alpha.

Prerequisites:
  • The cluster must be an RKE Kubernetes cluster.
  • The cluster must have been created with a default PodSecurityPolicy.

To enable pod security policy support when creating a Kubernetes cluster in the Rancher UI, go to Advanced Options. In the Pod Security Policy Support section, click Enabled. Then select a default pod security policy.

  1. Set the PodSecurityPolicy to unrestricted
  2. Enable the CNI
  3. Verify that the CNI is working.

1. Set the PodSecurityPolicy to unrestricted​

An unrestricted PSP allows Istio to be installed.

Set the PSP to unrestricted in the project where is Istio is installed, or the project where you plan to install Istio.

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. Click Cluster > Projects/Namespaces.
  4. Find the Project: System and select the ⋮ > Edit Config.
  5. Change the Pod Security Policy option to be unrestricted, then click Save.

2. Enable the CNI​

When installing or upgrading Istio through Apps & Marketplace,

  1. Click Components.
  2. Check the box next to Enabled CNI.
  3. Finish installing or upgrading Istio.

The CNI can also be enabled by editing the values.yaml:

istio_cni.enabled: true

Istio should install successfully with the CNI enabled in the cluster.

3. Verify that the CNI is working​

Verify that the CNI is working by deploying a sample application or deploying one of your own applications.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html b/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html index c5a5cdb742a..0481c24e33e 100644 --- a/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html +++ b/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html @@ -5,13 +5,13 @@ Additional Steps for Project Network Isolation | Rancher Manager - +
Version: v2.6

Additional Steps for Project Network Isolation

In clusters where:

  • You are using the Canal network plugin with Rancher before v2.5.8, or you are using Rancher v2.5.8+ with an any RKE network plug-in that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin
  • The Project Network Isolation option is enabled
  • You install the Istio Ingress module

The Istio Ingress Gateway pod won't be able to redirect ingress traffic to the workloads by default. This is because all the namespaces will be inaccessible from the namespace where Istio is installed. You have two options.

The first option is to add a new Network Policy in each of the namespaces where you intend to have ingress controlled by Istio. Your policy should include the following lines:

- podSelector:
    matchLabels:
      app: istio-ingressgateway

The second option is to move the istio-system namespace to the system project, which by default is excluded from the network isolation.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html b/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html index b6dadc77f3c..f64d60fdf14 100644 --- a/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html +++ b/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html @@ -5,13 +5,13 @@ Selectors and Scrape Configs | Rancher Manager - +
Version: v2.6

Selectors and Scrape Configs

The Monitoring app sets prometheus.prometheusSpec.ignoreNamespaceSelectors=false, which enables monitoring across all namespaces by default.

This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with istio-injection=enabled label.

If you would like to limit Prometheus to specific namespaces, set prometheus.prometheusSpec.ignoreNamespaceSelectors=true. Once you do this, you will need to add additional configuration to continue to monitor your resources.

Limiting Monitoring to Specific Namespaces by Setting ignoreNamespaceSelectors to True​

To limit monitoring to specific namespaces, you will edit the ignoreNamespaceSelectors Helm chart option. You will configure this option when installing or upgrading the Monitoring Helm chart:

  1. When installing or upgrading the Monitoring Helm chart, edit the values.yml and setprometheus.prometheusSpec.ignoreNamespaceSelectors=true.
  2. Complete the install or upgrade.

Result: Prometheus will be limited to specific namespaces which means one of the following configurations will need to be set up to continue to view data in various dashboards

Enabling Prometheus to Detect Resources in Other Namespaces​

There are two different ways to enable Prometheus to detect resources in other namespaces when prometheus.prometheusSpec.ignoreNamespaceSelectors=true:

  • Monitoring specific namespaces: Add a Service Monitor or Pod Monitor in the namespace with the targets you want to scrape.
  • Monitoring across namespaces: Add an additionalScrapeConfig to your rancher-monitoring instance to scrape all targets in all namespaces.

Monitoring Specific Namespaces: Create a Service Monitor or Pod Monitor​

This option allows you to define which specific services or pods you would like monitored in a specific namespace.

The usability tradeoff is that you have to create the service monitor or pod monitor per namespace since you cannot monitor across namespaces.

Prerequisite:

Define a ServiceMonitor or PodMonitor for <your namespace>. An example ServiceMonitor is provided below.

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. In the top navigation bar, open the kubectl shell.
  4. If the ServiceMonitor or PodMonitor file is stored locally in your cluster, in kubectl create -f <name of service/pod monitor file>.yaml.
  5. If the ServiceMonitor or PodMonitor is not stored locally, run cat<< EOF | kubectl apply -f -, paste the file contents into the terminal, then run EOF to complete the command.
  6. Run kubectl label namespace <your namespace> istio-injection=enabled to enable the envoy sidecar injection.

Result: <your namespace> can be scraped by prometheus.

Example Service Monitor for Istio Proxies
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: envoy-stats-monitor
  namespace: istio-system
  labels:
    monitoring: istio-proxies
spec:
  selector:
    matchExpressions:
    - {key: istio-prometheus-ignore, operator: DoesNotExist}
  namespaceSelector:
    any: true
  jobLabel: envoy-stats
  endpoints:
  - path: /stats/prometheus
    targetPort: 15090
    interval: 15s
    relabelings:
    - sourceLabels: [__meta_kubernetes_pod_container_port_name]
      action: keep
      regex: '.*-envoy-prom'
    - action: labeldrop
      regex: "__meta_kubernetes_pod_label_(.+)"
    - sourceLabels: [__meta_kubernetes_namespace]
      action: replace
      targetLabel: namespace
    - sourceLabels: [__meta_kubernetes_pod_name]
      action: replace
      targetLabel: pod_name

Monitoring across namespaces: Set ignoreNamespaceSelectors to False​

This enables monitoring across namespaces by giving Prometheus additional scrape configurations.

The usability tradeoff is that all of Prometheus' additionalScrapeConfigs are maintained in a single Secret. This could make upgrading difficult if monitoring is already deployed with additionalScrapeConfigs before installing Istio.

  1. When installing or upgrading the Monitoring Helm chart, edit the values.yml and set the prometheus.prometheusSpec.additionalScrapeConfigs array to the Additional Scrape Config provided below.
  2. Complete the install or upgrade.

Result: All namespaces with the istio-injection=enabled label will be scraped by prometheus.

Additional Scrape Config
- job_name: 'istio/envoy-stats'
  scrape_interval: 15s
  metrics_path: /stats/prometheus
  kubernetes_sd_configs:
    - role: pod
  relabel_configs:
    - source_labels: [__meta_kubernetes_pod_container_port_name]
      action: keep
      regex: '.*-envoy-prom'
    - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
      action: replace
      regex: ([^:]+)(?::\d+)?;(\d+)
      replacement: $1:15090
      target_label: __address__
    - action: labelmap
      regex: __meta_kubernetes_pod_label_(.+)
    - source_labels: [__meta_kubernetes_namespace]
      action: replace
      target_label: namespace
    - source_labels: [__meta_kubernetes_pod_name]
      action: replace
      target_label: pod_name
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html b/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html index ac4ed2ee928..37d18d1e823 100644 --- a/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html +++ b/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html @@ -5,13 +5,13 @@ CPU and Memory Allocations | Rancher Manager - +
Version: v2.6

CPU and Memory Allocations

This section describes the minimum recommended computing resources for the Istio components in a cluster.

The CPU and memory allocations for each component are configurable.

Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

tip

In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.

The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each core Istio component.

In Kubernetes, the resource request indicates that the workload will not deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the Kubernetes documentation.

WorkloadCPU - RequestMemory - RequestCPU - LimitMemory - Limit
ingress gateway100m128mi2000m1024mi
egress gateway100m128mi2000m1024mi
istiod500m2048miNo limitNo limit
proxy10m10mi2000m1024mi
Totals:710m2314Mi6000m3072Mi

Configuring Resource Allocations​

You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component.

To make it easier to schedule the workloads to a node, a cluster-admin can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend.

You can find more information about Istio configuration in the official Istio documentation.

To configure the resources allocated to an Istio component,

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. In the left navigation bar, click Apps & Marketplace.
  4. Click Installed Apps.
  5. Go to the istio-system namespace. In one of the Istio workloads, such as rancher-istio, click ⋮ > Edit/Upgrade.
  6. Click Upgrade to edit the base components via changes to the values.yaml or add an overlay file. For more information about editing the overlay file, see this section.
  7. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations.
  8. Click Upgrade. to rollout changes

Result: The resource allocations for the Istio components are updated.

Editing the Overlay File​

The overlay file can contain any of the values in the Istio Operator spec. The overlay file included with the Istio application is just one example of a potential configuration of the overlay file.

As long as the file contains kind: IstioOperator and the YAML options are valid, the file can be used as an overlay.

In the example overlay file provided with the Istio application, the following section allows you to change Kubernetes resources:

#      k8s:
#        resources:
#          requests:
#            cpu: 200m
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/disable-istio.html b/explanations/integrations-in-rancher/istio/disable-istio.html index 8b1b76bbca5..7920812bfbb 100644 --- a/explanations/integrations-in-rancher/istio/disable-istio.html +++ b/explanations/integrations-in-rancher/istio/disable-istio.html @@ -5,13 +5,13 @@ Disabling Istio | Rancher Manager - +
Version: v2.6

Disabling Istio

This section describes how to uninstall Istio in a cluster or disable a namespace, or workload.

Uninstall Istio in a Cluster​

To uninstall Istio,

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. In the left navigation bar, click Apps & Marketplace > Installed Apps.
  4. In the istio-system namespace, go to rancher-istio and click ⋮ > Delete.
  5. After rancher-istio is deleted, you can then select all the remaining apps in the istio-system namespace and click Delete.

Result: The rancher-istio app in the cluster gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster.

note

You can no longer disable and re-enable your Istio installation. If you would like to save your settings for a future install, view and save individual YAMLs to refer back to / reuse for future installations.

Troubleshooting Uninstall: If you didn't follow the uninstall steps, you may encounter a warning during uninstall:

Error: uninstallation completed with 1 error(s): unable to build kubernetes objects for delete: unable to recognize "": no matches for kind "MonitoringDashboard" in version "monitoring.kiali.io/v1alpha1"

This could mean a few things. You either selected all the apps in the istio-system namespace and deleted them at the same time, or you deleted rancher-istio chart dependencies prior to deleting the rancher-istio chart. Since the uninstall did not complete properly, you will have resources remaining in the istio-system namespace that you will need to manually clean up. Another option to avoid manual clean up is to install rancher-istio again, then uninstall it in the correct order.

Disable Istio in a Namespace​

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. Click Cluster > Projects/Namespaces.
  4. Go to the namespace where you want to enable Istio and click ⋮ > Enable Istio Auto Injection. Alternately, click the namespace, and then on the namespace detail page, click ⋮ > Enable Istio Auto Injection.

Result: When workloads are deployed in this namespace, they will not have the Istio sidecar.

Remove the Istio Sidecar from a Workload​

Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/istio/rbac-for-istio.html b/explanations/integrations-in-rancher/istio/rbac-for-istio.html index 6c3bf672c96..20dfc9ddccd 100644 --- a/explanations/integrations-in-rancher/istio/rbac-for-istio.html +++ b/explanations/integrations-in-rancher/istio/rbac-for-istio.html @@ -5,13 +5,13 @@ Role-based Access Control | Rancher Manager - +
Version: v2.6

Role-based Access Control

This section describes the permissions required to access Istio features.

The rancher istio chart installs three ClusterRoles

Cluster-Admin Access​

By default, only those with the cluster-admin ClusterRole can:

  • Install istio app in a cluster
  • Configure resource allocations for Istio

Admin and Edit access​

By default, only Admin and Edit roles can:

  • Enable and disable Istio sidecar auto-injection for namespaces
  • Add the Istio sidecar to workloads
  • View the traffic metrics and traffic graph for the cluster
  • Configure Istio's resources (such as the gateway, destination rules, or virtual services)

Summary of Default Permissions for Kubernetes Default roles​

Istio creates three ClusterRoles and adds Istio CRD access to the following default K8s ClusterRole:

ClusterRole create by chartDefault K8s ClusterRoleRancher Role
istio-adminadminProject Owner
istio-editeditProject Member
istio-viewviewRead-only

Rancher will continue to use cluster-owner, cluster-member, project-owner, project-member, etc as role names, but will utilize default roles to determine access. For each default K8s ClusterRole there are different Istio CRD permissions and K8s actions (Create ( C ), Get ( G ), List ( L ), Watch ( W ), Update ( U ), Patch ( P ), Delete( D ), All ( * )) that can be performed.

CRDsAdminEditView
  • config.istio.io
    • adapters
    • attributemanifests
    • handlers
    • httpapispecbindings
    • httpapispecs
    • instances
    • quotaspecbindings
    • quotaspecs
    • rules
    • templates
GLWGLWGLW
  • networking.istio.io
    • destinationrules
    • envoyfilters
    • gateways
    • serviceentries
    • sidecars
    • virtualservices
    • workloadentries
**GLW
  • security.istio.io
    • authorizationpolicies
    • peerauthentications
    • requestauthentications
**GLW
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html b/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html index 94acb9a778b..427d6f96132 100644 --- a/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html +++ b/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html @@ -5,13 +5,13 @@ Flows and ClusterFlows | Rancher Manager - +
Version: v2.6

Flows and ClusterFlows

For the full details on configuring Flows and ClusterFlows, see the Banzai Cloud Logging operator documentation.

Flows​

A Flow defines which logs to collect and filter and which output to send the logs to.

The Flow is a namespaced resource, which means logs will only be collected from the namespace that the Flow is deployed in.

Flows can be configured by filling out forms in the Rancher UI.

For more details about the Flow custom resource, see FlowSpec.

Matches​

Match statements are used to select which containers to pull logs from.

You can specify match statements to select or exclude logs according to Kubernetes labels, container and host names. Match statements are evaluated in the order they are defined and processed only until the first matching select or exclude rule applies.

Matches can be configured by filling out the Flow or ClusterFlow forms in the Rancher UI.

For detailed examples on using the match statement, see the official documentation on log routing.

Filters​

You can define one or more filters within a Flow. Filters can perform various actions on the logs, for example, add additional data, transform the logs, or parse values from the records. The filters in the Flow are applied in the order in the definition.

For a list of filters supported by the Banzai Cloud Logging operator, see this page.

Filters need to be configured in YAML.

Outputs​

This Output will receive logs from the Flow. Because the Flow is a namespaced resource, the Output must reside in same namespace as the Flow.

Outputs can be referenced when filling out the Flow or ClusterFlow forms in the Rancher UI.

ClusterFlows​

Matches, filters and Outputs are configured for ClusterFlows in the same way that they are configured for Flows. The key difference is that the ClusterFlow is scoped at the cluster level and can configure log collection across all namespaces.

ClusterFlows can be configured by filling out forms in the Rancher UI.

After ClusterFlow selects logs from all namespaces in the cluster, logs from the cluster will be collected and logged to the selected ClusterOutput.

YAML Example​

The following example Flow transforms the log messages from the default namespace and sends them to an S3 Output:

apiVersion: logging.banzaicloud.io/v1beta1
kind: Flow
metadata:
  name: flow-sample
  namespace: default
spec:
  filters:
    - parser:
        remove_key_name_field: true
        parse:
          type: nginx
    - tag_normaliser:
        format: ${namespace_name}.${pod_name}.${container_name}
  localOutputRefs:
    - s3-output
  match:
    - select:
        labels:
          app: nginx
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html b/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html index 0a807c82b9e..d6ccf6f27ca 100644 --- a/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html +++ b/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html @@ -5,13 +5,13 @@ Outputs and ClusterOutputs | Rancher Manager - +
Version: v2.6

Outputs and ClusterOutputs

For the full details on configuring Outputs and ClusterOutputs, see the Banzai Cloud Logging operator documentation.

Outputs​

The Output resource defines where your Flows can send the log messages. Outputs are the final stage for a logging Flow.

The Output is a namespaced resource, which means only a Flow within the same namespace can access it.

You can use secrets in these definitions, but they must also be in the same namespace.

Outputs can be configured by filling out forms in the Rancher UI.

For the details of Output custom resource, see OutputSpec.

The Rancher UI provides forms for configuring the following Output types:

  • Amazon ElasticSearch
  • Azure Storage
  • Cloudwatch
  • Datadog
  • Elasticsearch
  • File
  • Fluentd
  • GCS
  • Kafka
  • Kinesis Stream
  • LogDNA
  • LogZ
  • Loki
  • New Relic
  • Splunk
  • SumoLogic
  • Syslog

The Rancher UI provides forms for configuring the Output type, target, and access credentials if applicable.

For example configuration for each logging plugin supported by the logging operator, see the logging operator documentation.

ClusterOutputs​

ClusterOutput defines an Output without namespace restrictions. It is only effective when deployed in the same namespace as the logging operator.

ClusterOutputs can be configured by filling out forms in the Rancher UI.

For the details of the ClusterOutput custom resource, see ClusterOutput.

YAML Examples​

Once logging is installed, you can use these examples to help craft your own logging pipeline.

Cluster Output to ElasticSearch​

Let's say you wanted to send all logs in your cluster to an elasticsearch cluster. First, we create a cluster Output.

apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterOutput
metadata:
    name: "example-es"
    namespace: "cattle-logging-system"
spec:
    elasticsearch:
      host: elasticsearch.example.com
      port: 9200
      scheme: http

We have created this ClusterOutput, without elasticsearch configuration, in the same namespace as our operator: cattle-logging-system.. Any time we create a ClusterFlow or ClusterOutput, we have to put it in the cattle-logging-system namespace.

Now that we have configured where we want the logs to go, let's configure all logs to go to that ClusterOutput.

apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterFlow
metadata:
    name: "all-logs"
    namespace: "cattle-logging-system"
spec:
  globalOutputRefs:
    - "example-es"

We should now see our configured index with logs in it.

Output to Splunk​

What if we have an application team who only wants logs from a specific namespaces sent to a splunk server? For this case, we can use namespaced Outputs and Flows.

Before we start, let's set up that team's application: coolapp.

apiVersion: v1
kind: Namespace
metadata:
  name: devteam
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: coolapp
  namespace: devteam
  labels:
    app: coolapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: coolapp
  template:
    metadata:
      labels:
        app: coolapp
    spec:
      containers:
        - name: generator
          image: paynejacob/loggenerator:latest

With coolapp running, we will follow a similar path as when we created a ClusterOutput. However, unlike ClusterOutputs, we create our Output in our application's namespace.

apiVersion: logging.banzaicloud.io/v1beta1
kind: Output
metadata:
  name: "devteam-splunk"
  namespace: "devteam"
spec:
  splunkHec:
    hec_host: splunk.example.com
    hec_port: 8088
    protocol: http

Once again, let's feed our Output some logs:

apiVersion: logging.banzaicloud.io/v1beta1
kind: Flow
metadata:
  name: "devteam-logs"
  namespace: "devteam"
spec:
  localOutputRefs:
    - "devteam-splunk"

Output to Syslog​

Let's say you wanted to send all logs in your cluster to an syslog server. First, we create a ClusterOutput:

apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterOutput
metadata:
  name: "example-syslog"
  namespace: "cattle-logging-system"
spec:
  syslog:
    buffer:
      timekey: 30s
      timekey_use_utc: true
      timekey_wait: 10s
      flush_interval: 5s
    format:
      type: json
      app_name_field: test
    host: syslog.example.com
    insecure: true
    port: 514
    transport: tcp

Now that we have configured where we want the logs to go, let's configure all logs to go to that Output.

apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterFlow
metadata:
  name: "all-logs"
  namespace: cattle-logging-system
spec:
  globalOutputRefs:
    - "example-syslog"

Unsupported Outputs​

For the final example, we create an Output to write logs to a destination that is not supported out of the box:

Note on syslog:

syslog is a supported Output. However, this example still provides an overview on using unsupported plugins.

apiVersion: v1
kind: Secret
metadata:
  name: syslog-config
  namespace: cattle-logging-system
type: Opaque
stringData:
  fluent-bit.conf: |
    [INPUT]
        Name              forward
        Port              24224

    [OUTPUT]
        Name              syslog
        InstanceName      syslog-output
        Match             *
        Addr              syslog.example.com
        Port              514
        Cluster           ranchers

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fluentbit-syslog-forwarder
  namespace: cattle-logging-system
  labels:
    output: syslog
spec:
  selector:
    matchLabels:
      output: syslog
  template:
    metadata:
      labels:
        output: syslog
    spec:
      containers:
      - name: fluentbit
        image: paynejacob/fluent-bit-out-syslog:latest
        ports:
          - containerPort: 24224
        volumeMounts:
          - mountPath: "/fluent-bit/etc/"
            name: configuration
      volumes:
      - name: configuration
        secret:
          secretName: syslog-config
---
apiVersion: v1
kind: Service
metadata:
  name: syslog-forwarder
  namespace: cattle-logging-system
spec:
  selector:
    output: syslog
  ports:
    - protocol: TCP
      port: 24224
      targetPort: 24224
---
apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterFlow
metadata:
  name: all-logs
  namespace: cattle-logging-system
spec:
  globalOutputRefs:
    - syslog
---
apiVersion: logging.banzaicloud.io/v1beta1
kind: ClusterOutput
metadata:
  name: syslog
  namespace: cattle-logging-system
spec:
  forward:
    servers:
      - host: "syslog-forwarder.cattle-logging-system"
    require_ack_response: false
    ignore_network_errors_at_startup: false

Let's break down what is happening here. First, we create a deployment of a container that has the additional syslog plugin and accepts logs forwarded from another fluentd. Next we create an Output configured as a forwarder to our deployment. The deployment fluentd will then forward all logs to the configured syslog destination.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/logging-architecture.html b/explanations/integrations-in-rancher/logging/logging-architecture.html index b40a3dd3aa1..75522f3f1d0 100644 --- a/explanations/integrations-in-rancher/logging/logging-architecture.html +++ b/explanations/integrations-in-rancher/logging/logging-architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
Version: v2.6

Architecture

This section summarizes the architecture of the Rancher logging application.

For more details about how the Banzai Cloud Logging operator works, see the official documentation.

How the Banzai Cloud Logging Operator Works​

The Logging operator automates the deployment and configuration of a Kubernetes logging pipeline. It deploys and configures a Fluent Bit DaemonSet on every node to collect container and application logs from the node file system.

Fluent Bit queries the Kubernetes API and enriches the logs with metadata about the pods, and transfers both the logs and the metadata to Fluentd. Fluentd receives, filters, and transfers logs to multiple Outputs.

The following custom resources are used to define how logs are filtered and sent to their Outputs:

  • A Flow is a namespaced custom resource that uses filters and selectors to route log messages to the appropriate Outputs.
  • A ClusterFlow is used to route cluster-level log messages.
  • An Output is a namespaced resource that defines where the log messages are sent.
  • A ClusterOutput defines an Output that is available from all Flows and ClusterFlows.

Each Flow must reference an Output, and each ClusterFlow must reference a ClusterOutput.

The following figure from the Banzai documentation shows the new logging architecture:

How the Banzai Cloud Logging Operator Works with Fluentd and Fluent Bit

How the Banzai Cloud Logging Operator Works with Fluentd

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html b/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html index c341d1c47f6..9d03ddd6d49 100644 --- a/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html +++ b/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html @@ -5,14 +5,14 @@ rancher-logging Helm Chart Options | Rancher Manager - +
Version: v2.6

rancher-logging Helm Chart Options

Enable/Disable Windows Node Logging​

You can enable or disable Windows node logging by setting global.cattle.windows.enabled to either true or false in the values.yaml.

By default, Windows node logging will be enabled if the Cluster Dashboard UI is used to install the logging application on a Windows cluster.

In this scenario, setting global.cattle.windows.enabled to false will disable Windows node logging on the cluster. When disabled, logs will still be collected from Linux nodes within the Windows cluster.

note

Currently an issue exists where Windows nodeAgents are not deleted when performing a helm upgrade after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed.

Working with a Custom Docker Root Directory​

If using a custom Docker root directory, you can set global.dockerRootDirectory in values.yaml.

This will ensure that the Logging CRs created will use your specified path rather than the default Docker data-root location.

Note that this only affects Linux nodes.

If there are any Windows nodes in the cluster, the change will not be applicable to those nodes.

Adding NodeSelector Settings and Tolerations for Custom Taints​

You can add your own nodeSelector settings and add tolerations for additional taints by editing the logging Helm chart values. For details, see this page.

Enabling the Logging Application to Work with SELinux​

Requirements:

Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8.

Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8.

To use Logging v2 with SELinux, we recommend installing the rancher-selinux RPM according to the instructions on this page.

Then, when installing the logging application, configure the chart to be SELinux aware by changing global.seLinux.enabled to true in the values.yaml.

Additional Logging Sources​

By default, Rancher collects logs for control plane components and node components for all cluster types.

In some cases, Rancher may be able to collect additional logs.

The following table summarizes the sources where additional logs may be collected for each node types:

Logging SourceLinux Nodes (including in Windows cluster)Windows Nodes
RKE✓✓
RKE2✓
K3s✓
AKS✓
EKS✓
GKE✓

To enable hosted Kubernetes providers as additional logging sources, enable Enable enhanced cloud provider logging option when installing or upgrading the Logging Helm chart.

When enabled, Rancher collects all additional node and control plane logs the provider has made available, which may vary between providers

If you're already using a cloud provider's own logging solution such as AWS CloudWatch or Google Cloud operations suite (formerly Stackdriver), it is not necessary to enable this option as the native solution will have unrestricted access to all logs.

Systemd Configuration​

In Rancher logging, SystemdLogPath must be configured for K3s and RKE2 Kubernetes distributions.

K3s and RKE2 Kubernetes distributions log to journald, which is the subsystem of systemd that is used for logging. In order to collect these logs, the systemdLogPath needs to be defined. While the run/log/journal directory is used by default, some Linux distributions do not default to this path. For example, Ubuntu defaults to var/log/journal. To determine your systemdLogPath configuration, see steps below.

Steps for Systemd Configuration:

  • Run cat /etc/systemd/journald.conf | grep -E ^\#?Storage | cut -d"=" -f2 on one of your nodes.
  • If persistent is returned, your systemdLogPath should be /var/log/journal.
  • If volatile is returned, your systemdLogPath should be /run/log/journal.
  • If auto is returned, check if /var/log/journal exists.
    • If /var/log/journal exists, then use /var/log/journal.
    • If /var/log/journal does not exist, then use /run/log/journal.
Notes:

If any value not described above is returned, Rancher Logging will not be able to collect control plane logs. To address this issue, you will need to perform the following actions on every control plane node:

  • Set Storage=volatile in journald.conf.
  • Reboot your machine.
  • Set systemdLogPath to /run/log/journal.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html b/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html index e1bd1f8d24f..8f31a98f793 100644 --- a/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html +++ b/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html @@ -5,13 +5,13 @@ Migrating to Rancher v2.5 Logging | Rancher Manager - +
Version: v2.6

Migrating to Rancher v2.5 Logging

Starting in v2.5, the logging feature available within Rancher has been completely overhauled. The logging operator from Banzai Cloud has been adopted; Rancher configures this tooling for use when deploying logging.

Among the many features and changes in the new logging functionality is the removal of project-specific logging configurations. Instead, one now configures logging at the namespace level. Cluster-level logging remains available, but configuration options differ.

Installation​

To install logging in Rancher v2.5+, refer to the installation instructions.

Terminology​

In v2.5+, logging configuration in the Cluster Dashboard. To configure logging custom resources after the Logging application is installed, go to the left navigation bar and click Logging. It is from this menu option that logging for both cluster and namespace is configured.

note

Logging is installed on a per-cluster basis. You will need to navigate between clusters to configure logging for each cluster.

There are four key concepts to understand for v2.5+ logging:

  1. Outputs

    Outputs are a configuration resource that determine a destination for collected logs. This is where settings for aggregators such as ElasticSearch, Kafka, etc. are stored. Outputs are namespaced resources.

  2. Flows

    Flows are a configuration resource that determine collection, filtering, and destination rules for logs. It is within a flow that one will configure what logs to collect, how to mutate or filter them, and which Outputs to send the logs to. Flows are namespaced resources, and can connect either to an Output in the same namespace, or a ClusterOutput.

  3. ClusterOutputs

    ClusterOutputs serve the same functionality as Outputs, except they are a cluster-scoped resource. ClusterOutputs are necessary when collecting logs cluster-wide, or if you wish to provide an Output to all namespaces in your cluster.

  4. ClusterFlows

    ClusterFlows serve the same function as Flows, but at the cluster level. They are used to configure log collection for an entire cluster, instead of on a per-namespace level. ClusterFlows are also where mutations and filters are defined, same as Flows (in functionality).

Cluster Logging​

To configure cluster-wide logging for v2.5+ logging, one needs to set up a ClusterFlow. This object defines the source of logs, any transformations or filters to be applied, and finally the Output (or Outputs) for the logs.

Important:

ClusterFlows must be defined within the cattle-logging-system namespace. ClusterFlows will not work if defined in any other namespace.

In legacy logging, in order to collect logs from across the entire cluster, one only needed to enable cluster-level logging and define the desired Output. This basic approach remains in v2.5+ logging. To replicate legacy cluster-level logging, follow these steps:

  1. Define a ClusterOutput according to the instructions found under Output Configuration
  2. Create a ClusterFlow, ensuring that it is set to be created in the cattle-logging-system namespace
    1. Remove all Include and Exclude rules from the Flow definition. This ensures that all logs are gathered.
    2. You do not need to configure any filters if you do not wish - default behavior does not require their creation
    3. Define your cluster Output or Outputs

This will result in logs from all sources in the cluster (all pods, and all system components) being collected and sent to the Output or Outputs you defined in the ClusterFlow.

Project Logging​

Logging in v2.5+ is not project-aware. This means that in order to collect logs from pods running in project namespaces, you will need to define Flows for those namespaces.

To collect logs from a specific namespace, follow these steps:

  1. Define an Output or ClusterOutput according to the instructions found under Output Configuration
  2. Create a Flow, ensuring that it is set to be created in the namespace in which you want to gather logs.
    1. If you wish to define Include or Exclude rules, you may do so. Otherwise, removal of all rules will result in all pods in the target namespace having their logs collected.
    2. You do not need to configure any filters if you do not wish - default behavior does not require their creation
    3. Define your outputs - these can be either ClusterOutput or Output objects.

This will result in logs from all sources in the namespace (pods) being collected and sent to the Output (or Outputs) you defined in your Flow.

note

To collect logs from a project, repeat the above steps for every namespace within the project. Alternatively, you can label your project workloads with a common label (e.g. project=my-project) and use a ClusterFlow to collect logs from all pods matching this label.

Output Configuration​

In legacy logging, there are five logging destinations to choose from: Elasticsearch, Splunk, Kafka, Fluentd, and Syslog. With the exception of Syslog, all of these destinations are available in logging v2.5+.

Elasticsearch​

Legacy Loggingv2.5+ LoggingNotes
EndpointTarget -> HostMake sure to specify Scheme (https/http), as well as Port
X-Pack Security -> UsernameAccess -> User
X-Pack Security -> PasswordAccess -> PasswordPassword must now be stored in a secret
SSL Configuration -> Client Private KeySSL -> Client KeyKey must now be stored in a secret
SSL Configuration -> Client CertificateSSL -> Client CertCertificate must now be stored in a secret
SSL Configuration -> Client Key PasswordSSL -> Client Key PassPassword must now be stored in a secret
SSL Configuration -> Enabled SSL VerificationSSL -> Certificate Authority FileCertificate must now be stored in a secret

In legacy logging, indices were automatically created according to the format in the "Index Patterns" section. In v2.5 logging, default behavior has been changed to logging to a single index. You can still configure index pattern functionality on the Output object by editing as YAML and inputting the following values:

...
spec:
  elasticsearch:
    ...
    logstash_format: true
    logstash_prefix: <desired prefix>
    logstash_dateformat: "%Y-%m-%d"

Replace <desired prefix> with the prefix for the indices that will be created. In legacy logging, this defaulted to the name of the cluster.

Splunk​

Legacy Loggingv2.5+ LoggingNotes
HEC Configuration -> EndpointTarget -> HostProtocol (https/http) and port must be defined separately from the host
HEC Configuration -> TokenAccess -> TokenToken must now be stored as a secret
HEC Configuration -> IndexEdit as YAML -> indexindex field must be added as YAML key under spec.splunkHec
HEC Configuration -> SourceEdit as YAML -> sourcesource field must be added as YAML key under spec.splunkHec
SSL Configuration -> Client Private KeyEdit as YAML -> client_keyclient_key field must be added as YAML key under spec.splunkHec. See (1)
SSL Configuration -> Client CertificateEdit as YAML -> client_certclient_cert field must be added as YAML key under spec.splunkHec. See (1)
SSL Configuration -> Client Key PasswordNot SupportedSpecifying a password for the client private key is not currently supported.
SSL Configuration -> SSL VerifyEdit as YAML -> ca_file or ca_pathca_file or ca_path field must be added as YAML key under spec.splunkHec. See (2)

(1) client_key and client_cert values must be paths to the key and cert files, respectively. These files must be mounted into the rancher-logging-fluentd pod in order to be used.

(2) Users can configure either ca_file (a path to a PEM-encoded CA certificate) or ca_path (a path to a directory containing CA certificates in PEM format). These files must be mounted into the rancher-logging-fluentd pod in order to be used.

Kafka​

Legacy Loggingv2.5+ LoggingNotes
Kafka Configuration -> Endpoint Type-Zookeeper is no longer supported as an endpoint type
Kafka Configuration -> EndpointTarget -> BrokersComma-separated list of brokers (host:port)
Kafka Configuration -> TopicTarget -> Default Topic
SSL Configuration -> Client Private KeySSL -> SSL Client CertCertificate must be stored as a secret
SSL Configuration -> Client CertificateSSL -> SSL Client Cert KeyKey must be stored as a secret
SSL Configuration -> CA Certificate PEMSSL -> SSL CA CertCertificate must be stored as a secret
SASL Configuration -> UsernameAccess -> UsernameUsername must be stored in a secret
SASL Configuration -> PasswordAccess -> PasswordPassword must be stored in a secret
SASL Configuration -> Scram MechanismAccess -> Scram MechanismInput mechanism as string, e.g. "sha256" or "sha512"

Fluentd​

As of v2.5.2, it is only possible to add a single Fluentd server using the "Edit as Form" option. To add multiple servers, edit the Output as YAML and input multiple servers.

Legacy Loggingv2.5+ LoggingNotes
Fluentd Configuration -> EndpointTarget -> Host, PortInput the host and port separately
Fluentd Configuration -> Shared KeyAccess -> Shared KeyShared key must be stored as a secret
Fluentd Configuration -> UsernameAccess -> UsernameUsername must be stored as a secret
Fluentd Configuration -> PasswordAccess -> PasswordPassword must be stored as a secret
Fluentd Configuration -> HostnameEdit as YAML -> hosthost field set as YAML key under spec.forward.servers[n]
Fluentd Configuration -> WeightEdit as YAML -> weightweight field set as YAML key under spec.forward.servers[n]
SSL Configuration -> Use TLS-Do not need to explicitly enable. Define client cert fields instead.
SSL Configuration -> Client Private KeyEdit as YAML -> tls_private_key_pathField set as YAML key under spec.forward. See (1)
SSL Configuration -> Client CertificateEdit as YAML -> tls_client_cert_pathField set as YAML key under spec.forward. See (1)
SSL Configuration -> Client Key PasswordEdit as YAML -> tls_client_private_key_passphraseField set as YAML key under spec.forward. See (1)
SSL Configuration -> SSL VerifyEdit as YAML -> tls_insecure_modeField set as YAML key under spec.forward. Default: false
SSL Configuration -> CA Certificate PEMEdit as YAML -> tls_cert_pathField set as YAML key under spec.forward. See (1)
Enable Gzip Compression-No longer supported in v2.5+ logging

(1) These values are to be specified as paths to files. Those files must be mounted into the rancher-logging-fluentd pod in order to be used.

Syslog​

As of v2.5.2, syslog is not currently supported for Outputs using v2.5+ logging.

Custom Log Fields​

In order to add custom log fields, you will need to add the following YAML to your Flow configuration:

...
spec:
  filters:
    - record_modifier:
        records:
        - foo: "bar"

(replace foo: "bar" with custom log fields you wish to add)

System Logging​

In legacy logging, collecting logs from system components was accomplished by checking a box labeled "Include System Log" when setting up cluster logging. In v2.5+ logging, system logs are gathered in one of two ways:

  1. Gather all cluster logs, not specifying any match or exclusion rules. This results in all container logs from the cluster being collected, which includes system logs.
  2. Specifically target system logs by adding match rules for system components. Specific match rules depend on the component being collected.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/rbac-for-logging.html b/explanations/integrations-in-rancher/logging/rbac-for-logging.html index e743f7afa8d..403cfb0feb2 100644 --- a/explanations/integrations-in-rancher/logging/rbac-for-logging.html +++ b/explanations/integrations-in-rancher/logging/rbac-for-logging.html @@ -5,13 +5,13 @@ Role-based Access Control for Logging | Rancher Manager - +
Version: v2.6

Role-based Access Control for Logging

Rancher logging has two roles, logging-admin and logging-view.

  • logging-admin gives users full access to namespaced Flows and Outputs
  • logging-view allows users to view namespaced Flows and Outputs, and ClusterFlows and ClusterOutputs
Why choose one role over the other?

Edit access to ClusterFlow and ClusterOutput resources is powerful. Any user with it has edit access for all logs in the cluster.

In Rancher, the cluster administrator role is the only role with full access to all rancher-logging resources. Cluster members are not able to edit or read any logging resources. Project owners and members have the following privileges:

Project OwnersProject Members
able to create namespaced Flows and Outputs in their projects' namespacesonly able to view the Flows and Outputs in projects' namespaces
can collect logs from anything in their projects' namespacescannot collect any logs in their projects' namespaces

Both project owners and project members require at least one namespace in their project to use logging. If they do not, then they may not see the logging button in the top nav dropdown.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/logging/taints-and-tolerations.html b/explanations/integrations-in-rancher/logging/taints-and-tolerations.html index 3b4ad7d6cea..27ecf2ffd63 100644 --- a/explanations/integrations-in-rancher/logging/taints-and-tolerations.html +++ b/explanations/integrations-in-rancher/logging/taints-and-tolerations.html @@ -5,7 +5,7 @@ Working with Taints and Tolerations | Rancher Manager - + @@ -14,7 +14,7 @@ The logging stack pods have tolerations for this taint, which enables them to run on Linux nodes. Moreover, most logging stack pods run on Linux only and have a nodeSelector added to ensure they run on Linux nodes.

This example Pod YAML file shows a nodeSelector being used with a toleration:

apiVersion: v1
kind: Pod
# metadata...
spec:
  # containers...
  tolerations:
    - key: cattle.io/os
      operator: "Equal"
      value: "linux"
      effect: NoSchedule
  nodeSelector:
    kubernetes.io/os: linux

In the above example, we ensure that our pod only runs on Linux nodes, and we add a toleration for the taint we have on all of our Linux nodes.

You can do the same with Rancher's existing taints, or with your own custom ones.

Adding NodeSelector Settings and Tolerations for Custom Taints​

If you would like to add your own nodeSelector settings, or if you would like to add tolerations for additional taints, you can pass the following to the chart's values.

tolerations:
  # insert tolerations...
nodeSelector:
  # insert nodeSelector...

These values will add both settings to the fluentd, fluentbit, and logging-operator containers. Essentially, these are global settings for all pods in the logging stack.

However, if you would like to add tolerations for only the fluentbit container, you can add the following to the chart's values.

fluentbit_tolerations:
  # insert tolerations list for fluentbit containers only...
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/longhorn.html b/explanations/integrations-in-rancher/longhorn.html index a91e1f9de04..8694bb1b8d2 100644 --- a/explanations/integrations-in-rancher/longhorn.html +++ b/explanations/integrations-in-rancher/longhorn.html @@ -5,13 +5,13 @@ Longhorn - Cloud native distributed block storage for Kubernetes | Rancher Manager - +
Version: v2.6

Longhorn - Cloud native distributed block storage for Kubernetes

Longhorn is a lightweight, reliable, and easy-to-use distributed block storage system for Kubernetes.

Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI. You can learn more about its architecture here.

With Longhorn, you can:

  • Use Longhorn volumes as persistent storage for the distributed stateful applications in your Kubernetes cluster
  • Partition your block storage into Longhorn volumes so that you can use Kubernetes volumes with or without a cloud provider
  • Replicate block storage across multiple nodes and data centers to increase availability
  • Store backup data in external storage such as NFS or AWS S3
  • Create cross-cluster disaster recovery volumes so that data from a primary Kubernetes cluster can be quickly recovered from backup in a second Kubernetes cluster
  • Schedule recurring snapshots of a volume, and schedule recurring backups to NFS or S3-compatible secondary storage
  • Restore volumes from backup
  • Upgrade Longhorn without disrupting persistent volumes
Longhorn Dashboard

Longhorn Dashboard

Installing Longhorn with Rancher​

  1. Fulfill all Installation Requirements.
  2. Go to the cluster where you want to install Longhorn.
  3. Click Apps & Marketplace.
  4. Click Charts.
  5. Click Longhorn.
  6. Optional: To customize the initial settings, click Longhorn Default Settings and edit the configuration. For help customizing the settings, refer to the Longhorn documentation.
  7. Click Install.

Result: Longhorn is deployed in the Kubernetes cluster.

Accessing Longhorn from the Rancher UI​

  1. Go to the cluster where Longhorn is installed. In the left navigation menu, click Longhorn.
  2. On this page, you can edit Kubernetes resources managed by Longhorn. To view the Longhorn UI, click the Longhorn button in the Overview section.

Result: You will be taken to the Longhorn UI, where you can manage your Longhorn volumes and their replicas in the Kubernetes cluster, as well as secondary backups of your Longhorn storage that may exist in another Kubernetes cluster or in S3.

Uninstalling Longhorn from the Rancher UI​

  1. Go to the cluster where Longhorn is installed and click Apps & Marketplace.
  2. Click Installed Apps.
  3. Go to the longhorn-system namespace and check the boxes next to the longhorn and longhorn-crd apps.
  4. Click Delete, and confirm Delete.

Result: Longhorn is uninstalled.

GitHub Repository​

The Longhorn project is available here.

Documentation​

The Longhorn documentation is here.

Architecture​

Longhorn creates a dedicated storage controller for each volume and synchronously replicates the volume across multiple replicas stored on multiple nodes.

The storage controller and replicas are themselves orchestrated using Kubernetes.

You can learn more about its architecture here.

Longhorn Architecture

Longhorn Architecture

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html b/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html index 201888b5760..e6c792d459f 100644 --- a/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html +++ b/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html @@ -5,13 +5,13 @@ Built-in Dashboards | Rancher Manager - +
Version: v2.6

Built-in Dashboards

Grafana UI​

Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture.

To see the default dashboards for time series data visualization, go to the Grafana UI.

Customizing Grafana​

To view and customize the PromQL queries powering the Grafana dashboard, see this page.

Persistent Grafana Dashboards​

To create a persistent Grafana dashboard, see this page.

Access to Grafana​

For information about role-based access control for Grafana, see this section.

Alertmanager UI​

When rancher-monitoring is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration.

note

This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

Accessing the Alertmanager UI​

The Alertmanager UI lets you see the most recently fired alerts.

Prerequisite:

The rancher-monitoring application must be installed.

To see the Alertmanager UI,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to see the Alertmanager UI, click Explore.
  3. In the left navigation bar, click Monitoring.
  4. Click Alertmanager.

Result: The Alertmanager UI opens in a new tab. For help with configuration, refer to the official Alertmanager documentation.

For more information on configuring Alertmanager in Rancher, see this page.

The Alertmanager UI

Alertmanager UI

Viewing Default Alerts​

To see alerts that are fired by default, go to the Alertmanager UI and click Expand all groups.

Prometheus UI​

By default, the kube-state-metrics service provides a wealth of information about CPU and memory utilization to the monitoring application. These metrics cover Kubernetes resources across namespaces. This means that in order to see resource metrics for a service, you don't need to create a new ServiceMonitor for it. Because the data is already in the time series database, you can go to the Prometheus UI and run a PromQL query to get the information. The same query can be used to configure a Grafana dashboard to show a graph of those metrics over time.

To see the Prometheus UI, install rancher-monitoring. Then:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to see the Prometheus UI and click Explore.
  3. In the left navigation bar, click Monitoring.
  4. Click Prometheus Graph.
Prometheus Graph UI

Prometheus Graph UI

Viewing the Prometheus Targets​

To see what services you are monitoring, you will need to see your targets. Targets are set up by ServiceMonitors and PodMonitors as sources to scrape metrics from. You won't need to directly edit targets, but the Prometheus UI can be useful for giving you an overview of all of the sources of metrics that are being scraped.

To see the Prometheus Targets, install rancher-monitoring. Then:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to see the Prometheus targets and click Explore.
  3. In the left navigation bar, click Monitoring.
  4. Click Prometheus Targets.
Targets in the Prometheus UI

Prometheus Targets UI

Viewing the PrometheusRules​

When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the spec of the Rule itself contains labels that are used by Alertmanager to figure out which Route should receive a certain Alert.

To see the PrometheusRules, install rancher-monitoring. Then:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to see the visualizations and click Explore.
  3. In the left navigation bar, click Monitoring.
  4. Click Prometheus Rules.

You can also see the rules in the Prometheus UI:

Rules in the Prometheus UI

PrometheusRules UI

For more information on configuring PrometheusRules in Rancher, see this page.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html b/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html index 47c08aeb890..e80561b98ac 100644 --- a/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html +++ b/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html @@ -5,14 +5,14 @@ How Monitoring Works | Rancher Manager - +
Version: v2.6

How Monitoring Works

1. Architecture Overview​

The following sections describe how data flows through the Monitoring V2 application:

Prometheus Operator​

Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created. When the Prometheus configuration resources are created, Prometheus Operator calls the Prometheus API to sync the new configuration. As the diagram at the end of this section shows, the Prometheus Operator acts as the intermediary between Prometheus and Kubernetes, calling the Prometheus API to synchronize Prometheus with the monitoring-related resources in Kubernetes.

ServiceMonitors and PodMonitors​

ServiceMonitors and PodMonitors declaratively specify targets, such as Services and Pods, that need to be monitored.

  • Targets are scraped on a recurring schedule based on the configured Prometheus scrape interval, and the metrics that are scraped are stored into the Prometheus Time Series Database (TSDB).

  • In order to perform the scrape, ServiceMonitors and PodMonitors are defined with label selectors that determine which Services or Pods should be scraped and endpoints that determine how the scrape should happen on the given target, e.g., scrape/metrics in TCP 10252, proxying through IP addr x.x.x.x.

  • Out of the box, Monitoring V2 comes with certain pre-configured exporters that are deployed based on the type of Kubernetes cluster that it is deployed on. For more information, see Scraping and Exposing Metrics.

How PushProx Works​

  • Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. The Kubernetes components that expose metrics to Prometheus through PushProx are the following: kube-controller-manager, kube-scheduler, etcd, and kube-proxy.

  • For each PushProx exporter, we deploy one PushProx client onto all target nodes. For example, a PushProx client is deployed onto all controlplane nodes for kube-controller-manager, all etcd nodes for kube-etcd, and all nodes for kubelet.

  • We deploy exactly one PushProx proxy per exporter. The process for exporting metrics is as follows:

  1. The PushProx Client establishes an outbound connection with the PushProx Proxy.
  2. The client then polls the proxy for scrape requests that have come into the proxy.
  3. When the proxy receives a scrape request from Prometheus, the client sees it as a result of the poll.
  4. The client scrapes the internal component.
  5. The internal component responds by pushing metrics back to the proxy.

Process for Exporting Metrics with PushProx:

Process for Exporting Metrics with PushProx

PrometheusRules​

PrometheusRules allow users to define rules for what metrics or time series database queries should result in alerts being fired. Rules are evaluated on an interval.

  • Recording rules create a new time series based on existing series that have been collected. They are frequently used to precompute complex queries.
  • Alerting rules run a particular query and fire an alert from Prometheus if the query evaluates to a non-zero value.

Alert Routing​

Once Prometheus determines that an alert needs to be fired, alerts are forwarded to Alertmanager.

  • Alerts contain labels that come from the PromQL query itself and additional labels and annotations that can be provided as part of specifying the initial PrometheusRule.

  • Before receiving any alerts, Alertmanager will use the routes and receivers specified in its configuration to form a routing tree on which all incoming alerts are evaluated. Each node of the routing tree can specify additional grouping, labeling, and filtering that needs to happen based on the labels attached to the Prometheus alert. A node on the routing tree (usually a leaf node) can also specify that an alert that reaches it needs to be sent out to a configured Receiver, e.g., Slack, PagerDuty, SMS, etc. Note that Alertmanager will send an alert first to alertingDriver, then alertingDriver will send or forward alert to the proper destination.

  • Routes and receivers are also stored in the Kubernetes API via the Alertmanager Secret. When the Secret is updated, Alertmanager is also updated automatically. Note that routing occurs via labels only (not via annotations, etc.).

How data flows through the monitoring application:

2. How Prometheus Works​

Storing Time Series Data​

After collecting metrics from exporters, Prometheus stores the time series in a local on-disk time series database. Prometheus optionally integrates with remote systems, but rancher-monitoring uses local storage for the time series database.

Once stored, users can query this TSDB using PromQL, the query language for Prometheus.

PromQL queries can be visualized in one of two ways:

  1. By supplying the query in Prometheus's Graph UI, which will show a simple graphical view of the data.
  2. By creating a Grafana Dashboard that contains the PromQL query and additional formatting directives that label axes, add units, change colors, use alternative visualizations, etc.

Defining Rules for Prometheus​

Rules define queries that Prometheus needs to execute on a regular evaluationInterval to perform certain actions, such as firing an alert (alerting rules) or precomputing a query based on others existing in its TSDB (recording rules). These rules are encoded in PrometheusRules custom resources. When PrometheusRule custom resources are created or updated, the Prometheus Operator observes the change and calls the Prometheus API to synchronize the set of rules that Prometheus is currently evaluating on a regular interval.

A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:

  • The name of the new alert or record
  • A PromQL expression for the new alert or record
  • Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
  • Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.

On evaluating a rule, Prometheus will execute the provided PromQL query, add additional provided labels (or annotations - only for alerting rules), and execute the appropriate action for the rule. For example, an Alerting Rule that adds team: front-end as a label to the provided PromQL query will append that label to the fired alert, which will allow Alertmanager to forward the alert to the correct Receiver.

Alerting and Recording Rules​

Prometheus doesn't maintain the state of whether alerts are active. It fires alerts repetitively at every evaluation interval, relying on Alertmanager to group and filter the alerts into meaningful notifications.

The evaluation_interval constant defines how often Prometheus evaluates its alerting rules against the time series database. Similar to the scrape_interval, the evaluation_interval also defaults to one minute.

The rules are contained in a set of rule files. Rule files include both alerting rules and recording rules, but only alerting rules result in alerts being fired after their evaluation.

For recording rules, Prometheus runs a query, then stores it as a time series. This synthetic time series is useful for storing the results of an expensive or time-consuming query so that it can be queried more quickly in the future.

Alerting rules are more commonly used. Whenever an alerting rule evaluates to a positive number, Prometheus fires an alert.

The Rule file adds labels and annotations to alerts before firing them, depending on the use case:

  • Labels indicate information that identifies the alert and could affect the routing of the alert. For example, if when sending an alert about a certain container, the container ID could be used as a label.

  • Annotations denote information that doesn't affect where an alert is routed, for example, a runbook or an error message.

3. How Alertmanager Works​

The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of the following tasks:

  • Deduplicating, grouping, and routing alerts to the correct receiver integration such as email, PagerDuty, or OpsGenie

  • Silencing and inhibition of alerts

  • Tracking alerts that fire over time

  • Sending out the status of whether an alert is currently firing, or if it is resolved

Alerts Forwarded by alertingDrivers​

When alertingDrivers are installed, this creates a Service that can be used as the receiver's URL for Teams or SMS, based on the alertingDriver's configuration. The URL in the Receiver points to the alertingDrivers; so the Alertmanager sends alert first to alertingDriver, then alertingDriver forwards or sends alert to the proper destination.

Routing Alerts to Receivers​

Alertmanager coordinates where alerts are sent. It allows you to group alerts based on labels and fire them based on whether certain labels are matched. One top-level route accepts all alerts. From there, Alertmanager continues routing alerts to receivers based on whether they match the conditions of the next route.

While the Rancher UI forms only allow editing a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager Secret.

Configuring Multiple Receivers​

By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.

By editing custom YAML in the Alertmanager or Receiver configuration, you can also send alerts to multiple notification systems. For more information, see the section on configuring Receivers.

4. Monitoring V2 Specific Components​

Prometheus Operator introduces a set of Custom Resource Definitions that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster.

Prometheus Operator will automatically update your Prometheus configuration based on the live state of the resources and configuration options that are edited in the Rancher UI.

Resources Deployed by Default​

By default, a set of resources curated by the kube-prometheus project are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring/Alerting stack.

The resources that get deployed onto your cluster to support this solution can be found in the rancher-monitoring Helm chart, which closely tracks the upstream kube-prometheus-stack Helm chart maintained by the Prometheus community with certain changes tracked in the CHANGELOG.md.

Default Exporters​

Monitoring V2 deploys three default exporters that provide additional metrics for Prometheus to store:

  1. node-exporter: exposes hardware and OS metrics for Linux hosts. For more information on node-exporter, refer to the upstream documentation.

  2. windows-exporter: exposes hardware and OS metrics for Windows hosts (only deployed on Windows clusters). For more information on windows-exporter, refer to the upstream documentation.

  3. kube-state-metrics: expose additional metrics that track the state of resources contained in the Kubernetes API (e.g., pods, workloads, etc.). For more information on kube-state-metrics, refer to the upstream documentation.

ServiceMonitors and PodMonitors will scrape these exporters, as defined here. Prometheus stores these metrics, and you can query the results via either Prometheus's UI or Grafana.

See the architecture section for more information on recording rules, alerting rules, and Alertmanager.

Components Exposed in the Rancher UI​

When the monitoring application is installed, you will be able to edit the following components in the Rancher UI:

ComponentType of ComponentPurpose and Common Use Cases for Editing
ServiceMonitorCustom resourceSets up Kubernetes Services to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource.
PodMonitorCustom resourceSets up Kubernetes Pods to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource.
ReceiverConfiguration block (part of Alertmanager)Modifies information on where to send an alert (e.g., Slack, PagerDuty, etc.) and any necessary information to send the alert (e.g., TLS certs, proxy URLs, etc.). Automatically updates the Alertmanager custom resource.
RouteConfiguration block (part of Alertmanager)Modifies the routing tree that is used to filter, label, and group alerts based on labels and send them to the appropriate Receiver. Automatically updates the Alertmanager custom resource.
PrometheusRuleCustom resourceDefines additional queries that need to trigger alerts or define materialized views of existing series that are within Prometheus's TSDB. Automatically updates the Prometheus custom resource.

PushProx​

PushProx allows Prometheus to scrape metrics across a network boundary, which prevents users from having to expose metrics ports for internal Kubernetes components on each node in a Kubernetes cluster.

Since the metrics for Kubernetes components are generally exposed on the host network of nodes in the cluster, PushProx deploys a DaemonSet of clients that sit on the hostNetwork of each node and make an outbound connection to a single proxy that is sitting on the Kubernetes API. Prometheus can then be configured to proxy scrape requests through the proxy to each client, which allows it to scrape metrics from the internal Kubernetes components without requiring any inbound node ports to be open.

Refer to Scraping Metrics with PushProx for more.

5. Scraping and Exposing Metrics​

Defining what Metrics are Scraped​

ServiceMonitors and PodMonitors define targets that are intended for Prometheus to scrape. The Prometheus custom resource tells Prometheus which ServiceMonitors or PodMonitors it should use to find out where to scrape metrics from.

The Prometheus Operator observes the ServiceMonitors and PodMonitors. When it observes that they are created or updated, it calls the Prometheus API to update the scrape configuration in the Prometheus custom resource and keep it in sync with the scrape configuration in the ServiceMonitors or PodMonitors. This scrape configuration tells Prometheus which endpoints to scrape metrics from and how it will label the metrics from those endpoints.

Prometheus scrapes all of the metrics defined in its scrape configuration at every scrape_interval, which is one minute by default.

The scrape configuration can be viewed as part of the Prometheus custom resource that is exposed in the Rancher UI.

How the Prometheus Operator Sets up Metrics Scraping​

The Prometheus Deployment or StatefulSet scrapes metrics, and the configuration of Prometheus is controlled by the Prometheus custom resources. The Prometheus Operator watches for Prometheus and Alertmanager resources, and when they are created, the Prometheus Operator creates a Deployment or StatefulSet for Prometheus or Alertmanager with the user-defined configuration.

When the Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created, it knows that the scrape configuration needs to be updated in Prometheus. It updates Prometheus by first updating the configuration and rules files in the volumes of Prometheus's Deployment or StatefulSet. Then it calls the Prometheus API to sync the new configuration, resulting in the Prometheus Deployment or StatefulSet to be modified in place.

How Kubernetes Component Metrics are Exposed​

Prometheus scrapes metrics from deployments known as exporters, which export the time series data in a format that Prometheus can ingest. In Prometheus, time series consist of streams of timestamped values belonging to the same metric and the same set of labeled dimensions.

Scraping Metrics with PushProx​

Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. For detailed information on PushProx, refer here and to the above architecture section.

Scraping Metrics​

The following Kubernetes components are directly scraped by Prometheus:

  • kubelet*
  • ingress-nginx**
  • coreDns/kubeDns
  • kube-api-server

* You can optionally use hardenedKubelet.enabled to use a PushProx, but that is not the default.

** For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.

Scraping Metrics Based on Kubernetes Distribution​

Metrics are scraped differently based on the Kubernetes distribution. For help with terminology, refer here. For details, see the table below:

How Metrics are Exposed to Prometheus
Kubernetes ComponentRKERKE2KubeADMK3s
kube-controller-managerrkeControllerManager.enabledrke2ControllerManager.enabledkubeAdmControllerManager.enabledk3sServer.enabled
kube-schedulerrkeScheduler.enabledrke2Scheduler.enabledkubeAdmScheduler.enabledk3sServer.enabled
etcdrkeEtcd.enabledrke2Etcd.enabledkubeAdmEtcd.enabledNot available
kube-proxyrkeProxy.enabledrke2Proxy.enabledkubeAdmProxy.enabledk3sServer.enabled
kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubelet
ingress-nginx*Collects metrics directly exposed by kubelet, exposed by rkeIngressNginx.enabledCollects metrics directly exposed by kubelet, Exposed by rke2IngressNginx.enabledNot availableNot available
coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDns
kube-api-serverCollects metrics directly exposed by kube-api-serverCollects metrics directly exposed by kube-api-serverCollects metrics directly exposed by kube-appi-serverCollects metrics directly exposed by kube-api-server

* For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.

Terminology​

  • kube-scheduler: The internal Kubernetes component that uses information in the pod spec to decide on which node to run a pod.
  • kube-controller-manager: The internal Kubernetes component that is responsible for node management (detecting if a node fails), pod replication and endpoint creation.
  • etcd: The internal Kubernetes component that is the distributed key/value store which Kubernetes uses for persistent storage of all cluster information.
  • kube-proxy: The internal Kubernetes component that watches the API server for pods/services changes in order to maintain the network up to date.
  • kubelet: The internal Kubernetes component that watches the API server for pods on a node and makes sure they are running.
  • ingress-nginx: An Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.
  • coreDns/kubeDns: The internal Kubernetes component responsible for DNS.
  • kube-api-server: The main internal Kubernetes component that is responsible for exposing APIs for the other master components.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html b/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html index 5843e4a36c6..5ef9a03bc68 100644 --- a/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html +++ b/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html @@ -5,13 +5,13 @@ PromQL Expression Reference | Rancher Manager - +
Version: v2.6

PromQL Expression Reference

The PromQL expressions in this doc can be used to configure alerts.

For more information about querying the Prometheus time series database, refer to the official Prometheus documentation.

Cluster Metrics​

Cluster CPU Utilization​

CatalogExpression
Detail1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))
Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))

Cluster Load Average​

CatalogExpression
Detail
load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
Summary
load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})
load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})
load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})

Cluster Memory Utilization​

CatalogExpression
Detail1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)
Summary1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)

Cluster Disk Utilization​

CatalogExpression
Detail(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)
Summary(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})

Cluster Disk I/O​

CatalogExpression
Detail
readsum(rate(node_disk_read_bytes_total[5m])) by (instance)
writtensum(rate(node_disk_written_bytes_total[5m])) by (instance)
Summary
readsum(rate(node_disk_read_bytes_total[5m]))
writtensum(rate(node_disk_written_bytes_total[5m]))

Cluster Network Packets​

CatalogExpression
Detail
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
Summary
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

Cluster Network I/O​

CatalogExpression
Detail
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
Summary
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

Node Metrics​

Node CPU Utilization​

CatalogExpression
Detailavg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)
Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))

Node Load Average​

CatalogExpression
Detail
load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
Summary
load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})

Node Memory Utilization​

CatalogExpression
Detail1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})
Summary1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})

Node Disk Utilization​

CatalogExpression
Detail(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)
Summary(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})

Node Disk I/O​

CatalogExpression
Detail
readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))
Summary
readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))

Node Network Packets​

CatalogExpression
Detail
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
Summary
receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

Node Network I/O​

CatalogExpression
Detail
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
Summary
receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

Etcd Metrics​

Etcd Has a Leader​

max(etcd_server_has_leader)

Number of Times the Leader Changes​

max(etcd_server_leader_changes_seen_total)

Number of Failed Proposals​

sum(etcd_server_proposals_failed_total)

GRPC Client Traffic​

CatalogExpression
Detail
insum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)
outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)
Summary
insum(rate(etcd_network_client_grpc_received_bytes_total[5m]))
outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))

Peer Traffic​

CatalogExpression
Detail
insum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)
outsum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)
Summary
insum(rate(etcd_network_peer_received_bytes_total[5m]))
outsum(rate(etcd_network_peer_sent_bytes_total[5m]))

DB Size​

CatalogExpression
Detailsum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)
Summarysum(etcd_debugging_mvcc_db_total_size_in_bytes)

Active Streams​

CatalogExpression
Detail
lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)
watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)
Summary
lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})
watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})

Raft Proposals​

CatalogExpression
Detail
appliedsum(increase(etcd_server_proposals_applied_total[5m])) by (instance)
committedsum(increase(etcd_server_proposals_committed_total[5m])) by (instance)
pendingsum(increase(etcd_server_proposals_pending[5m])) by (instance)
failedsum(increase(etcd_server_proposals_failed_total[5m])) by (instance)
Summary
appliedsum(increase(etcd_server_proposals_applied_total[5m]))
committedsum(increase(etcd_server_proposals_committed_total[5m]))
pendingsum(increase(etcd_server_proposals_pending[5m]))
failedsum(increase(etcd_server_proposals_failed_total[5m]))

RPC Rate​

CatalogExpression
Detail
totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)
failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)
Summary
totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))
failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))

Disk Operations​

CatalogExpression
Detail
commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)
fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)
Summary
commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))
fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))

Disk Sync Duration​

CatalogExpression
Detail
walhistogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))
dbhistogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))
Summary
walsum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))
dbsum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))

Kubernetes Components Metrics​

API Server Request Latency​

CatalogExpression
Detailavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06
Summaryavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06

API Server Request Rate​

CatalogExpression
Detailsum(rate(apiserver_request_count[5m])) by (instance, code)
Summarysum(rate(apiserver_request_count[5m])) by (instance)

Scheduling Failed Pods​

CatalogExpression
Detailsum(kube_pod_status_scheduled{condition="false"})
Summarysum(kube_pod_status_scheduled{condition="false"})

Controller Manager Queue Depth​

CatalogExpression
Detail
volumessum(volumes_depth) by instance
deploymentsum(deployment_depth) by instance
replicasetsum(replicaset_depth) by instance
servicesum(service_depth) by instance
serviceaccountsum(serviceaccount_depth) by instance
endpointsum(endpoint_depth) by instance
daemonsetsum(daemonset_depth) by instance
statefulsetsum(statefulset_depth) by instance
replicationmanagersum(replicationmanager_depth) by instance
Summary
volumessum(volumes_depth)
deploymentsum(deployment_depth)
replicasetsum(replicaset_depth)
servicesum(service_depth)
serviceaccountsum(serviceaccount_depth)
endpointsum(endpoint_depth)
daemonsetsum(daemonset_depth)
statefulsetsum(statefulset_depth)
replicationmanagersum(replicationmanager_depth)

Scheduler E2E Scheduling Latency​

CatalogExpression
Detailhistogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06
Summarysum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)

Scheduler Preemption Attempts​

CatalogExpression
Detailsum(rate(scheduler_total_preemption_attempts[5m])) by (instance)
Summarysum(rate(scheduler_total_preemption_attempts[5m]))

Ingress Controller Connections​

CatalogExpression
Detail
readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)
waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)
writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)
acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)
activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)
handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)
Summary
readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"})
waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"})
writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"})
acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))
activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))
handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))

Ingress Controller Request Process Time​

CatalogExpression
Detailtopk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))
Summarytopk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))

Rancher Logging Metrics​

Fluentd Buffer Queue Rate​

CatalogExpression
Detailsum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)
Summarysum(rate(fluentd_output_status_buffer_queue_length[5m]))

Fluentd Input Rate​

CatalogExpression
Detailsum(rate(fluentd_input_status_num_records_total[5m])) by (instance)
Summarysum(rate(fluentd_input_status_num_records_total[5m]))

Fluentd Output Errors Rate​

CatalogExpression
Detailsum(rate(fluentd_output_status_num_errors[5m])) by (type)
Summarysum(rate(fluentd_output_status_num_errors[5m]))

Fluentd Output Rate​

CatalogExpression
Detailsum(rate(fluentd_output_status_num_records_total[5m])) by (instance)
Summarysum(rate(fluentd_output_status_num_records_total[5m]))

Workload Metrics​

Workload CPU Utilization​

CatalogExpression
Detail
cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
Summary
cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

Workload Memory Utilization​

CatalogExpression
Detailsum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)
Summarysum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})

Workload Network Packets​

CatalogExpression
Detail
receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
Summary
receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

Workload Network I/O​

CatalogExpression
Detail
receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
Summary
receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

Workload Disk I/O​

CatalogExpression
Detail
readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
Summary
readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

Pod Metrics​

Pod CPU Utilization​

CatalogExpression
Detail
cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
Summary
cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))

Pod Memory Utilization​

CatalogExpression
Detailsum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)
Summarysum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})

Pod Network Packets​

CatalogExpression
Detail
receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
Summary
receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

Pod Network I/O​

CatalogExpression
Detail
receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
Summary
receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

Pod Disk I/O​

CatalogExpression
Detail
readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
Summary
readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

Container Metrics​

Container CPU Utilization​

CatalogExpression
cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))

Container Memory Utilization​

sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})

Container Disk I/O​

CatalogExpression
readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html b/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html index 278b96dd63e..7ffd35b44a2 100644 --- a/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html +++ b/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html @@ -5,13 +5,13 @@ Role-based Access Control | Rancher Manager - +
Version: v2.6

Role-based Access Control

This section describes the expectations for RBAC for Rancher Monitoring.

Cluster Admins​

By default, only those with the cluster-admin ClusterRole should be able to:

  • Install the rancher-monitoring App onto a cluster and all other relevant configuration performed on the chart deploy
    • e.g. whether default dashboards are created, what exporters are deployed onto the cluster to collect metrics, etc.
  • Create / modify / delete Prometheus deployments in the cluster via Prometheus CRs
  • Create / modify / delete Alertmanager deployments in the cluster via Alertmanager CRs
  • Persist new Grafana dashboards or datasources via creating ConfigMaps in the appropriate namespace
  • Expose certain Prometheus metrics to the k8s Custom Metrics API for HPA via a Secret in the cattle-monitoring-system namespace

Users with Kubernetes ClusterRole-based Permissions​

The rancher-monitoring chart installs the following three ClusterRoles. By default, they aggregate into the corresponding k8s ClusterRoles:

ClusterRoleAggregates To Default K8s ClusterRole
monitoring-adminadmin
monitoring-editedit
monitoring-viewview

These ClusterRoles provide different levels of access to the Monitoring CRDs based on the actions that can be performed:

CRDs (monitoring.coreos.com)AdminEditView
  • prometheuses
  • alertmanagers
Get, List, WatchGet, List, WatchGet, List, Watch
  • servicemonitors
  • podmonitors
  • prometheusrules
**Get, List, Watch

On a high level, the following permissions are assigned by default as a result.

Users with Kubernetes Admin/Edit Permissions​

Only those with the the cluster-admin, admin or edit ClusterRole should be able to:

  • Modify the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs
  • Modify the alerting / recording rules of a Prometheus deployment via PrometheusRules CRs

Users with Kubernetes View Permissions​

Only those with who have some Kubernetes ClusterRole should be able to:

  • View the configuration of Prometheuses that are deployed within the cluster
  • View the configuration of Alertmanagers that are deployed within the cluster
  • View the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs
  • View the alerting/recording rules of a Prometheus deployment via PrometheusRules CRs

Additional Monitoring Roles​

Monitoring also creates additional Roles that are not assigned to users by default but are created within the cluster. They can be bound to a namespace by deploying a RoleBinding that references it. To define a RoleBinding with kubectl instead of through Rancher, click here.

Admins should use these roles to provide more fine-grained access to users:

RolePurpose
monitoring-config-adminAllow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
monitoring-config-editAllow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
monitoring-config-viewAllow admins to assign roles to users to be able to view Secrets and ConfigMaps within the cattle-monitoring-system namespace. Viewing Secrets / ConfigMaps in this namespace could allow users to observe the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
monitoring-dashboard-adminAllow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.
monitoring-dashboard-editAllow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.
monitoring-dashboard-viewAllow admins to assign roles to users to be able to view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.

Additional Monitoring ClusterRoles​

Monitoring also creates additional ClusterRoles that are not assigned to users by default but are created within the cluster. They are not aggregated by default but can be bound to a namespace by deploying a RoleBinding or ClusterRoleBinding that references it. To define a RoleBinding with kubectl instead of through Rancher, click here.

RolePurpose
monitoring-ui-viewAvailable as of Monitoring v2 14.5.100+ Provides read-only access to external Monitoring UIs by giving a user permission to list the Prometheus, Alertmanager, and Grafana endpoints and make GET requests to Prometheus, Grafana, and Alertmanager UIs through the Rancher proxy.

Assigning Roles and ClusterRoles with kubectl​

An alternative method to using Rancher to attach a Role or ClusterRole to a user or group is by defining bindings in YAML files that you create. You must first configure the RoleBinding with the YAML file, then you apply the config changes by running the kubectl apply command.

  • Roles: Below is an example of a YAML file to help you configure RoleBindings in Kubernetes. You will need to fill in the name below, and name is case-sensitive.
# monitoring-config-view-role-binding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: monitoring-config-view
  namespace: cattle-monitoring-system
roleRef:
  kind: Role
  name: monitoring-config-view
  apiGroup: rbac.authorization.k8s.io
subjects:
- kind: User
  name: u-b4qkhsnliz # this can be found via `kubectl get users -A`
  apiGroup: rbac.authorization.k8s.io

  • kubectl: Below is an example of a kubectl command used to apply the binding you've created in the YAML file. As noted, you will need to fill in your YAML filename accordingly.

    • **kubectl apply -f monitoring-config-view-role-binding.yaml

Users with Rancher Based Permissions​

The relationship between the default roles deployed by Rancher (i.e. cluster-owner, cluster-member, project-owner, project-member), the default Kubernetes roles, and the roles deployed by the rancher-monitoring chart are detailed in the table below:

Default Rancher Permissions and Corresponding Kubernetes ClusterRoles
Rancher RoleKubernetes RoleMonitoring ClusterRole / RoleClusterRoleBinding or RoleBinding?
cluster-ownercluster-adminN/AClusterRoleBinding
cluster-memberadminmonitoring-adminClusterRoleBinding
project-owneradminmonitoring-adminRoleBinding within Project namespace
project-membereditmonitoring-editRoleBinding within Project namespace

In addition to these default Roles, the following additional Rancher project roles can be applied to members of your Cluster to provide additional access to Monitoring. These Rancher Roles will be tied to ClusterRoles deployed by the Monitoring chart:

Non-default Rancher Permissions and Corresponding Kubernetes ClusterRoles
Rancher RoleKubernetes ClusterRoleAvailable In Rancher FromAvailable in Monitoring v2 From
View Monitoring*monitoring-ui-view2.4.8+9.4.204+

* A User bound to the View Monitoring Rancher Role only has permissions to access external Monitoring UIs if provided links to those UIs. In order to access the Monitoring Pane to get those links, the User must be a Project Member of at least one Project.

Differences in 2.5.x​

Users with the project-member or project-owners roles assigned will not be given access to either Prometheus or Grafana in Rancher 2.5.x since we only create Grafana or Prometheus on a cluster-level.

In addition, while project owners will still be only able to add ServiceMonitors / PodMonitors that scrape resources within their project's namespace by default, PrometheusRules are not scoped to a single namespace / project. Therefore, any alert rules or recording rules created by project-owners within their project namespace will be applied across the entire cluster, although they will be unable to view / edit / delete any rules that were created outside the project's namespace.

Assigning Additional Access​

If cluster-admins would like to provide additional admin/edit access to users outside of the roles offered by the rancher-monitoring chart, the following table identifies the potential impact:

CRDs (monitoring.coreos.com)Can it cause impact outside of a namespace / project?Impact
prometheusesYes, this resource can scrape metrics from any targets across the entire cluster (unless the Operator itself is otherwise configured).User will be able to define the configuration of new cluster-level Prometheus deployments that should be created in the cluster.
alertmanagersNoUser will be able to define the configuration of new cluster-level Alertmanager deployments that should be created in the cluster. Note: if you just want to allow users to configure settings like Routes and Receivers, you should just provide access to the Alertmanager Config Secret instead.
  • servicemonitors
  • podmonitors
No, not by default; this is configurable via ignoreNamespaceSelectors on the Prometheus CR.User will be able to set up scrapes by Prometheus on endpoints exposed by Services / Pods within the namespace they are given this permission in.
prometheusrulesYes, PrometheusRules are cluster-scoped.User will be able to define alert or recording rules on Prometheus based on any series collected across the entire cluster.
k8s ResourcesNamespaceCan it cause impact outside of a namespace / project?Impact
  • secrets
  • configmaps
cattle-monitoring-systemYes, Configs and Secrets in this namespace can impact the entire monitoring / alerting pipeline.User will be able to create or edit Secrets / ConfigMaps such as the Alertmanager Config, Prometheus Adapter Config, TLS secrets, additional Grafana datasources, etc. This can have broad impact on all cluster monitoring / alerting.
  • secrets
  • configmaps
cattle-dashboardsYes, Configs and Secrets in this namespace can create dashboards that make queries on all metrics collected at a cluster-level.User will be able to create Secrets / ConfigMaps that persist new Grafana Dashboards only.

Role-based Access Control for Grafana​

Rancher allows any users who are authenticated by Kubernetes and have access the Grafana service deployed by the Rancher Monitoring chart to access Grafana via the Rancher Dashboard UI. By default, all users who are able to access Grafana are given the Viewer role, which allows them to view any of the default dashboards deployed by Rancher.

However, users can choose to log in to Grafana as an Admin if necessary. The default Admin username and password for the Grafana instance will be admin/prom-operator, but alternative credentials can also be supplied on deploying or upgrading the chart.

To see the Grafana UI, install rancher-monitoring. Then:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to see the visualizations and click Explore.
  3. In the left navigation bar, click Monitoring.
  4. Click Grafana.
Cluster Compute Resources Dashboard in Grafana

Cluster Compute Resources Dashboard in Grafana

Default Dashboards in Grafana

Default Dashboards in Grafana

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html b/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html index 0cf04c27322..8265bd4e32b 100644 --- a/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html +++ b/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html @@ -5,13 +5,13 @@ Windows Cluster Support for Monitoring V2 | Rancher Manager - +
Version: v2.6

Windows Cluster Support for Monitoring V2

Available as of v2.5.8

Starting at Monitoring V2 14.5.100 (used by default in Rancher 2.5.8), Monitoring V2 can now be deployed on a Windows cluster and will scrape metrics from Windows nodes using prometheus-community/windows_exporter (previously named wmi_exporter).

Comparison to Monitoring V1​

Unlike Monitoring V1 for Windows, metrics collected by windows_exporter will be labeled as windows_ instead of wmi_ in accordance to a naming change from upstream from wmi_exporter to windows_exporter.

In addition, Monitoring V2 for Windows will no longer require users to keep port 9796 open on Windows hosts since the host metrics will published directly onto a port exposed on the windows-exporter Pod. This feature was powered by recent changes made by wins v0.1.0 to support publishing ports exposed on the hostNetwork on Pods that use wins to run a privileged Windows binary as a host process.

Cluster Requirements​

Monitoring V2 for Windows can only scrape metrics from Windows hosts that have a minimum wins version of v0.1.0. To be able to fully deploy Monitoring V2 for Windows, all of your hosts must meet this requirement.

If you provision a fresh RKE1 cluster in Rancher 2.5.8, your cluster should already meet this requirement.

Upgrading Existing Clusters to wins v0.1.0​

If the cluster was provisioned before Rancher 2.5.8 (even if the current Rancher version is 2.5.8), you will not be able to successfully deploy Monitoring V2 for Windows until you upgrade the wins version on each host to at least v0.1.0.

To facilitate this upgrade, Rancher 2.5.8 has released a brand new Helm chart called rancher-wins-upgrader.

Prerequisite: Make sure Monitoring V1 for Windows is uninstalled.

  1. Deploy rancher-wins-upgrader with the following override:

    # Masquerading bootstraps the wins-upgrader installation via
    # a previously whitelisted process path since the normal install path,
    # c:\etc\rancher\wins\wins-upgrade.exe is not normally whitelisted.
    # In this case, we are using the previously whitelisted process
    # path used by Monitoring V1.
    masquerade:
      enabled: true
      as: c:\\etc\wmi-exporter\wmi-exporter.exe
    Note for Non-Default Windows Prefix Path:

    • If you set up the RKE cluster with a cluster.yml that has a non-default win_prefix_path, you will need to update the masquerade.as field with your prefix path in place of c:\\.

    • For example, if you have win_prefix_path: 'c:\host\opt\', then you will need to set as: c:\host\opt\etc\wmi-exporter\wmi-exporter.exe.

  2. Once all your hosts have been successfully upgraded, please ensure that you deploy the Helm chart once again with default values to avoid conflicts with the following settings:

    masquerade:
      enabled: false

Result: The hosts are ready for Monitoring V2 to be installed. You may choose to uninstall the rancher-wins-upgrader chart or keep it in your cluster to facilitate future upgrades.

For more information on how it can be used, please see the README.md of the chart.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/neuvector.html b/explanations/integrations-in-rancher/neuvector.html index 550f20c1927..adc65eb56a1 100644 --- a/explanations/integrations-in-rancher/neuvector.html +++ b/explanations/integrations-in-rancher/neuvector.html @@ -5,13 +5,13 @@ NeuVector Integration | Rancher Manager - +
Version: v2.6

NeuVector Integration

NeuVector Integration in Rancher​

New in Rancher v2.6.5, NeuVector 5.x is an open-source container-centric security platform that is now integrated into Rancher. NeuVector offers real-time compliance, visibility, and protection for critical applications and data during runtime. NeuVector provides a firewall, container process/file system monitoring, security auditing with CIS benchmarks, and vulnerability scanning. For more information on Rancher security, please see the security documentation.

NeuVector can be enabled through a Helm chart that may be installed either through Apps & Marketplace or through the Cluster Tools button in the Rancher UI. Once the Helm chart is installed, users can easily deploy and manage NeuVector clusters within Rancher.

Installing NeuVector with Rancher​

The Harvester Helm Chart is used to manage access to the NeuVector UI in Rancher where users can navigate directly to deploy and manage their NeuVector clusters.

To navigate to and install the NeuVector chart through Apps & Marketplace:

  1. Click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click Explore.
  3. Go to Apps & Marketplace > Charts, and install NeuVector from the chart repo.
  4. Different cluster types require different container runtimes. When configuring Helm chart values, go to the Container Runtime section, and select your runtime in accordance with the cluster type. Finally, click Install again.

Some examples are as follows:

  • RKE1: docker

  • K3s and RKE2: k3scontainerd

  • AKS: containerd for v1.19 and up

  • EKS: docker for v1.22 and below; containerd for v1.23 and up

  • GKE: containerd (see the Google docs for more)

    note

    Only one container runtime engine may be selected at a time during installation.

To navigate to and install the NeuVector chart through Cluster Tools:

  1. Click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster where you want to deploy NeuVector, and click Explore.
  3. Click on Cluster Tools at the bottom of the left navigation bar.
  4. Repeat step 4 above to select your container runtime accordingly, then click Install again.

Accessing NeuVector from the Rancher UI​

  1. Navigate to the cluster explorer of the cluster where NeuVector is installed. In the left navigation bar, click NeuVector.
  2. Click the external link to go to the NeuVector UI. Once the link is selected, users must accept the END USER LICENSE AGREEMENT to access the NeuVector UI.

Uninstalling NeuVector from the Rancher UI​

To uninstall from Apps & Marketplace:

  1. Click ☰ > Cluster Management.
  2. Under Apps & Marketplace, click Installed Apps.
  3. Under cattle-neuvector-system, select both the NeuVector app (and the associated CRD if desired), then click Delete.

To uninstall from Cluster Tools:

  1. Click ☰ > Cluster Management.
  2. Click on Cluster Tools at the bottom-left of the screen, then click on the trash can icon under the NeuVector chart. Select Delete the CRD associated with this app if desired, then click Delete.

GitHub Repository​

The NeuVector project is available here.

Documentation​

The NeuVector documentation is here.

Architecture​

The NeuVector security solution contains four types of security containers: Controllers, Enforcers, Managers, and Scanners. A special container called an All-in-One is also provided to combine the Controller, Enforcer, and Manager functions all in one container, primarily for Docker-native deployments. There is also an Updater which, when run, will update the CVE database.

  • Controller: Manages the NeuVector Enforcer container; provides REST APIs for the management console.
  • Enforcer: Enforces security policies.
  • Manager: Provides a web-UI and CLI console to manage the NeuVector platform.
  • All-in-One: Includes the Controller, Enforcer, and Manager.
  • Scanner: Performs the vulnerability and compliance scanning for images, containers, and nodes.
  • Updater: Updates the CVE database for Neuvector (when run); redeploys scanner pods.
**NeuVector Security Containers:**

NeuVector Security Containers

**NeuVector Architecture:**

NeuVector Architecture

To learn more about NeuVector's architecture, please refer here.

CPU and Memory Allocations​

Below are the minimum recommended computing resources for the NeuVector chart installation in a default deployment. Note that the resource limit is not set.

ContainerCPU - RequestMemory - Request
Controller3 (1GB 1vCPU needed per controller)*
EnforcerOn all nodes (500MB .5vCPU)1GB
Manager1 (500MB .5vCPU)*
Scanner3 (100MB .5vCPU)*

* Minimum 1GB of memory total required for Controller, Manager, and Scanner containers combined.

Hardened Cluster Support - Calico and Canal​

  • All NeuVector components are deployable if PSP is set to true.

    New in v2.6.7

    You will need to set additional configuration for your hardened cluster environment as follows:

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. In the left navigation bar, click Apps & Marketplace.
  4. Install (or upgrade to) NeuVector version 100.0.1+up2.2.2.

  • Under Edit Options > Other Configuration, enable Pod Security Policy by checking the box (no other config needed):

    Enable PSP for RKE1 Hardened Cluster

  1. Click Install at the bottom-right to complete.

SELinux-enabled Cluster Support - Calico and Canal​

To enable SELinux on RKE2 clusters, follow the steps below:

  • NeuVector components Controller and Enforcer are deployable if PSP is set to true.

Applicable to NeuVector chart version 100.0.0+up2.2.0 only:

  • For Manager, Scanner, and Updater components, additional configuration is required as shown below:
kubectl patch deploy neuvector-manager-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
kubectl patch deploy neuvector-scanner-pod -n cattle-neuvector-system --patch '{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}'
kubectl patch cronjob neuvector-updater-pod -n cattle-neuvector-system --patch '{"spec":{"jobTemplate":{"spec":{"template":{"spec":{"securityContext":{"runAsUser": 5400}}}}}}}'

Cluster Support in an Air-Gapped Environment​

  • All NeuVector components are deployable on a cluster in an air-gapped environment without any additional configuration needed.

Support Limitations​

  • Only admins and cluster owners are currently supported.

  • Fleet multi-cluster deployment is not supported.

  • NeuVector is not supported on a Windows cluster.

Other Limitations​

  • Currently, NeuVector feature chart installation fails when a NeuVector partner chart already exists. To work around this issue, uninstall the NeuVector partner chart and reinstall the NeuVector feature chart.

  • Sometimes when the controllers are not ready, the NeuVector UI is not accessible from the Rancher UI. During this time, controllers will try to restart, and it takes a few minutes for the controllers to be active.

  • Container runtime is not auto-detected for different cluster types when installing the NeuVector chart. To work around this, you can specify the runtime manually.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/explanations/integrations-in-rancher/opa-gatekeeper.html b/explanations/integrations-in-rancher/opa-gatekeeper.html index f1ce0a5e726..523d85dcd13 100644 --- a/explanations/integrations-in-rancher/opa-gatekeeper.html +++ b/explanations/integrations-in-rancher/opa-gatekeeper.html @@ -5,13 +5,13 @@ OPA Gatekeeper | Rancher Manager - +
Version: v2.6

OPA Gatekeeper

To ensure consistency and compliance, every organization needs the ability to define and enforce policies in its environment in an automated way. OPA (Open Policy Agent) is a policy engine that facilitates policy-based control for cloud native environments. Rancher provides the ability to enable OPA Gatekeeper in Kubernetes clusters, and also installs a couple of built-in policy definitions, which are also called constraint templates.

OPA provides a high-level declarative language that lets you specify policy as code and ability to extend simple APIs to offload policy decision-making.

OPA Gatekeeper is a project that provides integration between OPA and Kubernetes. OPA Gatekeeper provides:

  • An extensible, parameterized policy library.
  • Native Kubernetes CRDs for instantiating the policy library, also called “constraints."
  • Native Kubernetes CRDs for extending the policy library, also called "constraint templates."
  • Audit functionality.

To read more about OPA, please refer to the official documentation.

How the OPA Gatekeeper Integration Works​

Kubernetes provides the ability to extend API server functionality via admission controller webhooks, which are invoked whenever a resource is created, updated or deleted. Gatekeeper is installed as a validating webhook and enforces policies defined by Kubernetes custom resource definitions. In addition to the admission control usage, Gatekeeper provides the capability to audit existing resources in Kubernetes clusters and mark current violations of enabled policies.

OPA Gatekeeper is made available via Rancher's Helm system chart, and it is installed in a namespace named gatekeeper-system.

Enabling OPA Gatekeeper in a Cluster​

note

In Rancher v2.5, the OPA Gatekeeper application was improved. The Rancher v2.4 feature can't be upgraded to the new version in Rancher v2.5. If you installed OPA Gatekeeper in Rancher v2.4, you will need to uninstall OPA Gatekeeper and its CRDs from the old UI, then reinstall it in Rancher v2.5. To uninstall the CRDs run the following command in the kubectl console kubectl delete crd configs.config.gatekeeper.sh constrainttemplates.templates.gatekeeper.sh.

Prerequisite:

Only administrators and cluster owners can enable OPA Gatekeeper.

The OPA Gatekeeper Helm chart can be installed from Apps & Marketplace.

Enabling OPA Gatekeeper​

  1. In the upper left corner, click ☰ > Cluster Management.
  2. In the Clusters page, go to the cluster where you want to enable OPA Gatekeeper and click Explore.
  3. In the left navigation bar, click Apps & Marketplace.
  4. Click Charts and click OPA Gatekeeper.
  5. Click Install.

Result: OPA Gatekeeper is deployed in your Kubernetes cluster.

Constraint Templates​

Constraint templates are Kubernetes custom resources that define the schema and Rego logic of the OPA policy to be applied by Gatekeeper. For more information on the Rego policy language, refer to the official documentation.

When OPA Gatekeeper is enabled, Rancher installs some templates by default.

To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on Templates.

Rancher also provides the ability to create your own constraint templates by importing YAML definitions.

Creating and Configuring Constraints​

Constraints are Kubernetes custom resources that define the scope of objects to which a specific constraint template applies to. The complete policy is defined by constraint templates and constraints together.

Prerequisite:

OPA Gatekeeper must be enabled in the cluster.

To list the constraints installed, go to the left side menu under OPA Gatekeeper, and click on Constraints.

New constraints can be created from a constraint template.

Rancher provides the ability to create a constraint by using a convenient form that lets you input the various constraint fields.

The Edit as yaml option is also available to configure the the constraint's yaml definition.

Exempting Rancher's System Namespaces from Constraints​

When a constraint is created, ensure that it does not apply to any Rancher or Kubernetes system namespaces. If the system namespaces are not excluded, then it is possible to see many resources under them marked as violations of the constraint.

To limit the scope of the constraint only to user namespaces, always specify these namespaces under the Match field of the constraint.

Also, the constraint may interfere with other Rancher functionality and deny system workloads from being deployed. To avoid this, exclude all Rancher-specific namespaces from your constraints.

Enforcing Constraints in your Cluster​

When the Enforcement Action is Deny, the constraint is immediately enabled and will deny any requests that violate the policy defined. By default, the enforcement value is Deny.

When the Enforcement Action is Dryrun, then any resources that violate the policy are only recorded under the constraint's status field.

To enforce constraints, create a constraint using the form. In the Enforcement Action field, choose Deny.

Audit and Violations in your Cluster​

OPA Gatekeeper runs a periodic audit to check if any existing resource violates any enforced constraint. The audit-interval (default 300s) can be configured while installing Gatekeeper.

On the Gatekeeper page, any violations of the defined constraints are listed.

Also under Constraints, the number of violations of the constraint can be found.

The detail view of each constraint lists information about the resource that violated the constraint.

Disabling Gatekeeper​

  1. Navigate to the cluster's Dashboard view
  2. On the left side menu, expand the cluster menu and click on OPA Gatekeeper.
  3. Click the ⋮ > Disable.

Result: Upon disabling OPA Gatekeeper, all constraint templates and constraints will also be deleted.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq.html b/faq.html index 3194b117569..d71edd7c934 100644 --- a/faq.html +++ b/faq.html @@ -5,13 +5,13 @@ FAQ | Rancher Manager - +
Version: v2.6

FAQ

This FAQ is a work in progress designed to answers the questions our users most frequently ask about Rancher v2.x.

See Technical FAQ, for frequently asked technical questions.


Does Rancher v2.x support Docker Swarm and Mesos as environment types?

When creating an environment in Rancher v2.x, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm.


Is it possible to manage Azure Kubernetes Services with Rancher v2.x?

Yes.


Does Rancher support Windows?

As of Rancher 2.3.0, we support Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on configuring custom clusters for Windows.


Does Rancher support Istio?

As of Rancher 2.3.0, we support Istio.

Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along with any CNCF compliant Kubernetes cluster. You can read more about it here


Will Rancher v2.x support Hashicorp's Vault for storing secrets?

Secrets management is on our roadmap but we haven't assigned it to a specific release yet.


Does Rancher v2.x support RKT containers as well?

At this time, we only support Docker.


Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and registered Kubernetes?

Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave. Always refer to the Rancher Support Matrix for details about what is officially supported.


Are you planning on supporting Traefik for existing setups?

We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches.


Can I import OpenShift Kubernetes clusters into v2.x?

Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.


Are you going to integrate Longhorn?

Yes. Longhorn was integrated into Rancher v2.5+.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/container-network-interface-providers.html b/faq/container-network-interface-providers.html index 3c2642b3b5f..49503b82efb 100644 --- a/faq/container-network-interface-providers.html +++ b/faq/container-network-interface-providers.html @@ -5,13 +5,13 @@ Container Network Interface (CNI) Providers | Rancher Manager - +
Version: v2.6

Container Network Interface (CNI) Providers

What is CNI?​

CNI (Container Network Interface), a Cloud Native Computing Foundation project, consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted.

Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking.

CNI Logo

For more information visit CNI GitHub project.

What Network Models are Used in CNI?​

CNI network providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan (VXLAN) or an unencapsulated network model such as Border Gateway Protocol (BGP).

What is an Encapsulated Network?​

This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP.

In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected.

This network model is used when an extended L2 bridge is preferred. This network model is sensitive to L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation.

CNI network providers using this network model include Flannel, Canal, Weave, and Cilium. By default, Calico is not using this model, but it can be configured to do so.

Encapsulated Network

What is an Unencapsulated Network?​

This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as BGP.

In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods.

This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensitive to latency.

CNI network providers using this network model include Calico and Cilium. Cilium may be configured with this model although it is not the default mode.

Unencapsulated Network

What CNI Providers are Provided by Rancher?​

RKE Kubernetes clusters​

Out-of-the-box, Rancher provides the following CNI network providers for RKE Kubernetes clusters: Canal, Flannel, Calico, and Weave.

You can choose your CNI network provider when you create new Kubernetes clusters from Rancher.

Canal​

Canal Logo

Canal is a CNI network provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options.

In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation.

Kubernetes workers should open UDP port 8472 (VXLAN) and TCP port 9099 (health checks). If using Wireguard, you should open UDP ports 51820 and 51821. For more details, refer to the port requirements for user clusters.

For more information, see the Canal GitHub Page.

Flannel​

Flannel Logo

Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being VXLAN.

Encapsulated traffic is unencrypted by default. Flannel provides two solutions for encryption:

  • IPSec, which makes use of strongSwan to establish encrypted IPSec tunnels between Kubernetes workers. It is an experimental backend for encryption.
  • WireGuard, which is a more faster-performing alternative to strongSwan.

Kubernetes workers should open UDP port 8472 (VXLAN). See the port requirements for user clusters for more details.

Flannel Diagram

For more information, see the Flannel GitHub Page.

Weave​

Weave Logo

Weave enables networking and network policy in Kubernetes clusters across the cloud. Additionally, it support encrypting traffic between the peers.

Kubernetes workers should open TCP port 6783 (control port), UDP port 6783 and UDP port 6784 (data ports). See the port requirements for user clusters for more details.

For more information, see the following pages:

RKE2 Kubernetes clusters​

Out-of-the-box, Rancher provides the following CNI network providers for RKE2 Kubernetes clusters: Canal (see above section), Calico, and Cilium.

You can choose your CNI network provider when you create new Kubernetes clusters from Rancher.

Calico​

Calico Logo

Calico enables networking and network policy in Kubernetes clusters across the cloud. By default, Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-prem using BGP.

Calico also provides a stateless IP-in-IP or VXLAN encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies.

Kubernetes workers should open TCP port 179 if using BGP or UDP port 4789 if using VXLAN encapsulation. In addition, TCP port 5473 is needed when using Typha. See the port requirements for user clusters for more details.

Important:

In Rancher v2.6.3, Calico probes fail on Windows nodes upon RKE2 installation. Note that this issue is resolved in v2.6.4.

  • To work around this issue, first navigate to https://<rancherserverurl>/v3/settings/windows-rke2-install-script.

  • There, change the current setting: https://raw.githubusercontent.com/rancher/wins/v0.1.3/install.ps1 to this new setting: https://raw.githubusercontent.com/rancher/rke2/master/windows/rke2-install.ps1.

Calico Diagram

For more information, see the following pages:

Cilium​

Cilium Logo

Cilium enables networking and network policies (L3, L4, and L7) in Kubernetes. By default, Cilium uses eBPF technologies to route packets inside the node and VXLAN to send packets to other nodes. Unencapsulated techniques can also be configured.

Cilium recommends kernel versions greater than 5.2 to be able to leverage the full potential of eBPF. Kubernetes workers should open TCP port 8472 for VXLAN and TCP port 4240 for health checks. In addition, ICMP 8/0 must be enabled for health checks. For more information, check Cilium System Requirements.

Ingress Routing Across Nodes in Cilium​

By default, Cilium does not allow pods to contact pods on other nodes. To work around this, enable the ingress controller to route requests across nodes with a `CiliumNetworkPolicy`.

After selecting the Cilium CNI and enabling Project Network Isolation for your new cluster, configure as follows:

apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
  name: hn-nodes
  namespace: default
spec:
  endpointSelector: {}
  ingress:
    - fromEntities:
      - remote-node

CNI Features by Provider​

The following table summarizes the different features available for each CNI network provider provided by Rancher.

ProviderNetwork ModelRoute DistributionNetwork PoliciesMeshExternal DatastoreEncryptionIngress/Egress Policies
CanalEncapsulated (VXLAN)NoYesNoK8s APIYesYes
FlannelEncapsulated (VXLAN)NoNoNoK8s APIYesNo
CalicoEncapsulated (VXLAN,IPIP) OR UnencapsulatedYesYesYesEtcd and K8s APIYesYes
WeaveEncapsulatedYesYesYesNoYesYes
CiliumEncapsulated (VXLAN)YesYesYesEtcd and K8s APIYesYes

  • Network Model: Encapsulated or unencapsulated. For more information, see What Network Models are Used in CNI?

  • Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI network providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have.

  • Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with certain networking plugins.

  • Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters.

  • External Datastore: CNI network providers with this feature need an external datastore for its data.

  • Encryption: This feature allows cyphered and secure network control and data planes.

  • Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications.

CNI Community Popularity​

The following table summarizes different GitHub metrics to give you an idea of each project's popularity and activity. This data was collected in January 2022.

ProviderProjectStarsForksContributors
Canalhttps://github.com/projectcalico/canal67910021
Flannelhttps://github.com/flannel-io/flannel7k2.5k185
Calicohttps://github.com/projectcalico/calico3.1k741224
Weavehttps://github.com/weaveworks/weave/6.2k63584
Ciliumhttps://github.com/cilium/cilium10.6k1.3k352

Which CNI Provider Should I Use?​

It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs.

Canal is the default CNI network provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking.

How can I configure a CNI network provider?​

Please see Cluster Options on how to configure a network provider for your cluster. For more advanced configuration options, please see how to configure your cluster using a Config File and the options for Network Plug-ins.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/deprecated-features-in-v2.5.html b/faq/deprecated-features-in-v2.5.html index f11b9a45e0e..f331f108455 100644 --- a/faq/deprecated-features-in-v2.5.html +++ b/faq/deprecated-features-in-v2.5.html @@ -5,13 +5,13 @@ Deprecated Features in Rancher | Rancher Manager - +
Version: v2.6

Deprecated Features in Rancher

What is Rancher's Deprecation policy?​

We have published our official deprecation policy in the support terms of service.

Where can I find out which features have been deprecated in Rancher?​

Rancher will publish deprecated features as part of the release notes for Rancher found on GitHub. Please consult the following patch releases for deprecated features:

Patch VersionRelease Date
2.6.0Aug 31, 2021
2.6.1Oct 11, 2021
2.6.2Oct 19, 2021
2.6.3Dec 21, 2021
2.6.4Mar 31, 2022
2.6.5May 12, 2022
2.6.6Jun 30, 2022

What can I expect when a feature is marked for deprecation?​

In the release where functionality is marked as "Deprecated", it will still be available and supported allowing upgrades to follow the usual procedure. Once upgraded, users/admins should start planning to move away from the deprecated functionality before upgrading to the release it marked as removed. The recommendation for new deployments is to not use the deprecated feature.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/dockershim.html b/faq/dockershim.html index d5f42ba51a5..58e8360962d 100644 --- a/faq/dockershim.html +++ b/faq/dockershim.html @@ -5,13 +5,13 @@ Dockershim | Rancher Manager - +
Version: v2.6

Dockershim

The Dockershim is the CRI compliant layer between the Kubelet and the Docker daemon. As part of the Kubernetes 1.20 release, the deprecation of the in-tree Dockershim was announced. Removal is currently scheduled for Kubernetes 1.24. For more information on the deprecation and its timelines, see the Kubernetes Dockershim Deprecation FAQ.

RKE clusters, starting with Kubernetes 1.21, now support the external Dockershim to continue leveraging Docker as the CRI runtime. We now implement the upstream open source community Dockershim announced by Mirantis and Docker to ensure RKE clusters can continue to leverage Docker.

To enable the external Dockershim, configure the following option.

enable_cri_dockerd: true

For users looking to use another container runtime, Rancher has the edge-focused K3s and datacenter-focused RKE2 Kubernetes distributions that use containerd as the default runtime. Imported RKE2 and K3s Kubernetes clusters can then be upgraded and managed through Rancher even after the removal of in-tree Dockershim in Kubernetes 1.24.

FAQ​


Q. Do I have to upgrade Rancher to get Rancher’s support of the upstream Dockershim?

The upstream support of Dockershim begins for RKE in Kubernetes 1.21. You will need to be on Rancher 2.6 or above to have support for RKE with Kubernetes 1.21. See our support matrix for details.


Q. I am currently on RKE with Kubernetes 1.20. Do I need to upgrade to RKE with Kubernetes 1.21 sooner to avoid being out of support for Dockershim?

A. The version of Dockershim in RKE with Kubernetes 1.20 will continue to work and is not scheduled for removal upstream until Kubernetes 1.24. It will only emit a warning of its future deprecation, which Rancher has mitigated in RKE with Kubernetes 1.21. You can plan your upgrade to Kubernetes 1.21 as you would normally, but should consider enabling the external Dockershim by Kubernetes 1.22. The external Dockershim will need to be enabled before upgrading to Kubernetes 1.24, at which point the existing implementation will be removed.

For more information on the deprecation and its timeline, see the Kubernetes Dockershim Deprecation FAQ.


Q: What are my other options if I don’t want to depend on the Dockershim?

A: You can use a runtime like containerd with Kubernetes that does not require Dockershim support. RKE2 or K3s are two options for doing this.


Q: If I am already using RKE1 and want to switch to RKE2, what are my migration options?

A: Rancher is exploring the possibility of an in-place upgrade path. Alternatively you can always migrate workloads from one cluster to another using kubectl.


Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/install-and-configure-kubectl.html b/faq/install-and-configure-kubectl.html index 524dc09cc3e..3f0e00b86ae 100644 --- a/faq/install-and-configure-kubectl.html +++ b/faq/install-and-configure-kubectl.html @@ -5,13 +5,13 @@ Installing and Configuring kubectl | Rancher Manager - +
Version: v2.6

Installing and Configuring kubectl

kubectl is a CLI utility for running commands against Kubernetes clusters. It's required for many maintenance and administrative tasks in Rancher 2.x.

Installation​

See kubectl Installation for installation on your operating system.

Configuration​

When you create a Kubernetes cluster with RKE, RKE creates a kube_config_cluster.yml in the local directory that contains credentials to connect to your new cluster with tools like kubectl or helm.

You can copy this file as $HOME/.kube/config or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_cluster.yml.

export KUBECONFIG=$(pwd)/kube_config_cluster.yml

Test your connectivity with kubectl and see if you can get the list of nodes back.

kubectl get nodes
 NAME                          STATUS    ROLES                      AGE       VERSION
165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.10.1
165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.10.1
165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.10.1
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/networking.html b/faq/networking.html index 8ae320159d2..641e25f9f71 100644 --- a/faq/networking.html +++ b/faq/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/rancher-is-no-longer-needed.html b/faq/rancher-is-no-longer-needed.html index a38076fd23d..93a00ff1797 100644 --- a/faq/rancher-is-no-longer-needed.html +++ b/faq/rancher-is-no-longer-needed.html @@ -5,13 +5,13 @@ Rancher is No Longer Needed | Rancher Manager - +
Version: v2.6

Rancher is No Longer Needed

This page is intended to answer questions about what happens if you don't want Rancher anymore, if you don't want a cluster to be managed by Rancher anymore, or if the Rancher server is deleted.

If the Rancher server is deleted, what happens to the workloads in my downstream clusters?​

If Rancher is ever deleted or unrecoverable, all workloads in the downstream Kubernetes clusters managed by Rancher will continue to function as normal.

If the Rancher server is deleted, how do I access my downstream clusters?​

The capability to access a downstream cluster without Rancher depends on the type of cluster and the way that the cluster was created. To summarize:

  • Registered clusters: The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher.
  • Hosted Kubernetes clusters: If you created the cluster in a cloud-hosted Kubernetes provider such as EKS, GKE, or AKS, you can continue to manage the cluster using your provider's cloud credentials.
  • RKE clusters: To access an RKE cluster, the cluster must have the authorized cluster endpoint enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. (The authorized cluster endpoint is enabled by default for RKE clusters.) With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's authentication proxy. For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with kubectl and the kubeconfig file. These clusters will use a snapshot of the authentication as it was configured when Rancher was removed.

What if I don't want Rancher anymore?​

note

The previously recommended System Tools has been deprecated since June 2022.

If you installed Rancher on a Kubernetes cluster, remove Rancher by using the Rancher Cleanup tool.

As of Rancher v2.5.8, uninstalling Rancher in high-availability (HA) mode will also remove all helm-operation-* pods and the following apps:

  • fleet
  • fleet-agent
  • rancher-operator
  • rancher-webhook

Custom resources (CRDs) and custom namespaces will still need to be manually removed.

If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in.

Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on accessing downstream clusters when Rancher is removed.

What if I don't want my registered cluster managed by Rancher?​

If a registered cluster is deleted from the Rancher UI, the cluster is detached from Rancher, leaving it intact and accessible by the same methods that were used to access it before it was registered in Rancher.

To detach the cluster,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. Go to the registered cluster that should be detached from Rancher and click ⋮ > Delete.
  3. Click Delete.

Result: The registered cluster is detached from Rancher and functions normally outside of Rancher.

What if I don't want my RKE cluster or hosted Kubernetes cluster managed by Rancher?​

At this time, there is no functionality to detach these clusters from Rancher. In this context, "detach" is defined as the ability to remove Rancher components from the cluster and manage access to the cluster independently of Rancher.

The capability to manage these clusters without Rancher is being tracked in this issue.

For information about how to access clusters if the Rancher server is deleted, refer to this section.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/security.html b/faq/security.html index 0c6bc3f6c00..7c5039fe25a 100644 --- a/faq/security.html +++ b/faq/security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
Version: v2.6

Security

Is there a Hardening Guide?

The Hardening Guide is now located in the main Security section.


What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?

We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main Security section.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/technical-items.html b/faq/technical-items.html index 33788c805a7..8ddf3483e22 100644 --- a/faq/technical-items.html +++ b/faq/technical-items.html @@ -5,13 +5,13 @@ Technical | Rancher Manager - +
Version: v2.6

Technical

How can I reset the administrator password?​

Docker Install:

$ docker exec -ti <container_id> reset-password
New password for default administrator (user-xxxxx):
<new_password>

Kubernetes install (Helm):

$ KUBECONFIG=./kube_config_cluster.yml
$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher --no-headers | head -1 | awk '{ print $1 }') -c rancher -- reset-password
New password for default administrator (user-xxxxx):
<new_password>

I deleted/deactivated the last admin, how can I fix it?​

Docker Install:

$ docker exec -ti <container_id> ensure-default-admin
New default administrator (user-xxxxx)
New password for default administrator (user-xxxxx):
<new_password>

Kubernetes install (Helm):

$ KUBECONFIG=./kube_config_cluster.yml
$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin
New password for default administrator (user-xxxxx):
<new_password>

How can I enable debug logging?​

See Troubleshooting: Logging

My ClusterIP does not respond to ping​

ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using curl to access the IP and port to see if it responds.

Where can I manage Node Templates?​

Node Templates can be accessed by opening your account menu (top right) and selecting Node Templates.

Why is my Layer-4 Load Balancer in Pending state?​

The Layer-4 Load Balancer is created as type: LoadBalancer. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in Pending state forever. More information can be found on Cloud Providers or Create External Load Balancer

Where is the state of Rancher stored?​

  • Docker Install: in the embedded etcd of the rancher/rancher container, located at /var/lib/rancher.
  • Kubernetes install: in the etcd of the RKE cluster created to run Rancher.

How are the supported Docker versions determined?​

We follow the validated Docker versions for upstream Kubernetes releases. The validated versions can be found under External Dependencies in the Kubernetes release CHANGELOG.md.

How can I access nodes created by Rancher?​

SSH keys to access the nodes created by Rancher can be downloaded via the Nodes view. Choose the node which you want to access and click on the vertical ⋮ button at the end of the row, and choose Download Keys as shown in the picture below.

Download Keys

Unzip the downloaded zip file, and use the file id_rsa to connect to you host. Be sure to use the correct username (rancher or docker for RancherOS, ubuntu for Ubuntu, ec2-user for Amazon Linux)

$ ssh -i id_rsa user@ip_of_node

How can I automate task X in Rancher?​

The UI consists of static files, and works based on responses of the API. That means every action/task that you can execute in the UI, can be automated via the API. There are 2 ways to do this:

  • Visit https://your_rancher_ip/v3 and browse the API options.
  • Capture the API calls when using the UI (Most commonly used for this is Chrome Developer Tools but you can use anything you like)

The IP address of a node changed, how can I recover?​

A node is required to have a static IP configured (or a reserved IP via DHCP). If the IP of a node has changed, you will have to remove it from the cluster and readd it. After it is removed, Rancher will update the cluster to the correct state. If the cluster is no longer in Provisioning state, the node is removed from the cluster.

When the IP address of the node changed, Rancher lost connection to the node, so it will be unable to clean the node properly. See Cleaning cluster nodes to clean the node.

When the node is removed from the cluster, and the node is cleaned, you can readd the node to the cluster.

How can I add additional arguments/binds/environment variables to Kubernetes components in a Rancher Launched Kubernetes cluster?​

You can add additional arguments/binds/environment variables via the Config File option in Cluster Options. For more information, see the Extra Args, Extra Binds, and Extra Environment Variables in the RKE documentation or browse the Example Cluster.ymls.

How do I check if my certificate chain is valid?​

Use the openssl verify command to validate your certificate chain:

tip

Configure SSL_CERT_DIR and SSL_CERT_FILE to a dummy location to make sure the OS-installed certificates are not used when verifying manually.

SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem
rancher.yourdomain.com.pem: OK

If you receive the error unable to get local issuer certificate, the chain is incomplete. This usually means that there is an intermediate CA certificate that issued your server certificate. If you already have this certificate, you can use it in the verification of the certificate like shown below:

SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem
rancher.yourdomain.com.pem: OK

If you have successfully verified your certificate chain, you should include needed intermediate CA certificates in the server certificate to complete the certificate chain for any connection made to Rancher (for example, by the Rancher agent). The order of the certificates in the server certificate file should be first the server certificate itself (contents of rancher.yourdomain.com.pem), followed by intermediate CA certificate(s) (contents of intermediate.pem).

-----BEGIN CERTIFICATE-----
%YOUR_CERTIFICATE%
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
%YOUR_INTERMEDIATE_CERTIFICATE%
-----END CERTIFICATE-----

If you still get errors during verification, you can retrieve the subject and the issuer of the server certificate using the following command:

openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem
subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com
issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA

How do I check Common Name and Subject Alternative Names in my server certificate?​

Although technically an entry in Subject Alternative Names is required, having the hostname in both Common Name and as entry in Subject Alternative Names gives you maximum compatibility with older browser/applications.

Check Common Name:

openssl x509 -noout -subject -in cert.pem
subject= /CN=rancher.my.org

Check Subject Alternative Names:

openssl x509 -noout -in cert.pem -text | grep DNS
                DNS:rancher.my.org

Why does it take 5+ minutes for a pod to be rescheduled when a node has failed?​

This is due to a combination of the following default Kubernetes settings:

  • kubelet
    • node-status-update-frequency: Specifies how often kubelet posts node status to master (default 10s)
  • kube-controller-manager
    • node-monitor-period: The period for syncing NodeStatus in NodeController (default 5s)
    • node-monitor-grace-period: Amount of time which we allow running Node to be unresponsive before marking it unhealthy (default 40s)
    • pod-eviction-timeout: The grace period for deleting pods on failed nodes (default 5m0s)

See Kubernetes: kubelet and Kubernetes: kube-controller-manager for more information on these settings.

In Kubernetes v1.13, the TaintBasedEvictions feature is enabled by default. See Kubernetes: Taint based Evictions for more information.

  • kube-apiserver (Kubernetes v1.13 and up)
    • default-not-ready-toleration-seconds: Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration.
    • default-unreachable-toleration-seconds: Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration.

Can I use keyboard shortcuts in the UI?​

Yes, most parts of the UI can be reached using keyboard shortcuts. For an overview of the available shortcuts, press ? anywhere in the UI.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/faq/telemetry.html b/faq/telemetry.html index eb7dbe9c366..302369f8c28 100644 --- a/faq/telemetry.html +++ b/faq/telemetry.html @@ -5,13 +5,13 @@ Telemetry | Rancher Manager - +
Version: v2.6

Telemetry

What is Telemetry?​

Telemetry collects aggregate information about the size of Rancher installations, versions of components used, and which features are used. This information is used by Rancher Labs to help make the product better and is not shared with third-parties.

What information is collected?​

No specific identifying information like usernames, passwords, or the names or addresses of user resources will ever be collected.

The primary things collected include:

  • Aggregate counts (smallest, average, largest, total) of nodes per-cluster and their size (e.g. CPU cores & RAM).
  • Aggregate counts of logical resources like Clusters, Projects, Namespaces, and Pods.
  • Counts of what driver was used to deploy clusters and nodes (e.g. GKE vs EC2 vs Imported vs Custom).
  • Versions of Kubernetes components, Operating Systems and Docker that are deployed on nodes.
  • Whether some optional components are enabled or not (e.g. which auth providers are used).
  • The image name & version of Rancher that is running.
  • A unique randomly-generated identifier for this installation.

Can I see the information that is being sent?​

If Telemetry is enabled, you can go to https://<your rancher server>/v1-telemetry in your installation to see the current data.

If Telemetry is not enabled, the process that collects the data is not running, so there is nothing being collected to look at.

How do I turn it on or off?​

After initial setup, an administrator can go to the Settings page in the Global section of the UI and click Edit to change the telemetry-opt setting to either in or out.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started.html b/getting-started.html index 0592abadea6..deb7b1f0b7f 100644 --- a/getting-started.html +++ b/getting-started.html @@ -5,13 +5,13 @@ Getting Started | Rancher Manager - +
Version: v2.6

Getting Started

To get up and running with Rancher quickly, we have included a Getting Started section.

The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

Please see the introduction, quick start guides, and the installation and upgrade sections for more.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html index 82651d9f2d5..6382edc5c26 100644 --- a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html +++ b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html @@ -5,13 +5,13 @@ Docker Install with TLS Termination at Layer-7 NGINX Load Balancer | Rancher Manager - +
Version: v2.6

Docker Install with TLS Termination at Layer-7 NGINX Load Balancer

For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction.

A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.

This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.

Requirements for OS, Docker, Hardware, and Networking​

Make sure that your node fulfills the general installation requirements.

Installation Outline​

1. Provision Linux Host​

Provision a single Linux host according to our Requirements to launch your Rancher Server.

2. Choose an SSL Option and Install Rancher​

For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

Do you want to..
  • Complete an Air Gap Installation?
  • Record all transactions with the Rancher API?

See Advanced Options below before continuing.

Choose from the following options:

Option A-Bring Your Own Certificate: Self-Signed

If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate.

Prerequisites:

Create a self-signed certificate.

  • The certificate files must be in PEM format.

To Install Rancher Using a Self-Signed Cert:

  1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
      rancher/rancher:latest
Option B-Bring Your Own Certificate: Signed by Recognized CA

If your cluster is public facing, it's best to use a certificate signed by a recognized CA.

Prerequisites:
  • The certificate files must be in PEM format.

To Install Rancher Using a Cert Signed by a Recognized CA:

If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the --no-cacerts parameter to the container.

  1. Enter the following command.

    ```
    docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    rancher/rancher:latest --no-cacerts
    ```

3. Configure Load Balancer​

When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header X-Forwarded-Proto: https header, this redirect is disabled.

The load balancer or proxy has to be configured to support the following:

  • WebSocket connections

  • SPDY / HTTP/2 protocols

  • Passing / setting the following headers:

    HeaderValueDescription
    HostHostname used to reach Rancher.To identify the server requested by the client.
    X-Forwarded-ProtohttpsTo identify the protocol that a client used to connect to the load balancer or proxy.

    Note: If this header is present, rancher/rancher does not redirect HTTP to HTTPS.
    X-Forwarded-PortPort used to reach Rancher.To identify the protocol that client used to connect to the load balancer or proxy.
    X-Forwarded-ForIP of the client connection.To identify the originating IP address of a client.

Example NGINX configuration​

This NGINX configuration is tested on NGINX 1.14.

note

This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

  • Replace rancher-server with the IP address or hostname of the node running the Rancher container.
  • Replace both occurrences of FQDN to the DNS name for Rancher.
  • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
worker_processes 4;
worker_rlimit_nofile 40000;

events {
    worker_connections 8192;
}

http {
    upstream rancher {
        server rancher-server:80;
    }

    map $http_upgrade $connection_upgrade {
        default Upgrade;
        ''      close;
    }

    server {
        listen 443 ssl http2;
        server_name FQDN;
        ssl_certificate /certs/fullchain.pem;
        ssl_certificate_key /certs/privkey.pem;

        location / {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Port $server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass http://rancher;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
            proxy_read_timeout 900s;
            proxy_buffering off;
        }
    }

    server {
        listen 80;
        server_name FQDN;
        return 301 https://$server_name$request_uri;
    }
}

What's Next?​

  • Recommended: Review Single Node Backup and Restore. Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
  • Create a Kubernetes cluster: Provisioning Kubernetes Clusters.

FAQ and Troubleshooting​

For help troubleshooting certificates, see this section.

Advanced Options​

API Auditing​

If you want to record all transactions with the Rancher API, enable the API Auditing feature by adding the flags below into your install command.

-e AUDIT_LEVEL=1 \
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
-e AUDIT_LOG_MAXAGE=20 \
-e AUDIT_LOG_MAXBACKUP=20 \
-e AUDIT_LOG_MAXSIZE=100 \

Air Gap​

If you are visiting this page to complete an Air Gap Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

Example:

 <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

Persistent Data​

Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

You can bind mount a host volume to this location to preserve data on the host it is running on:

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /opt/rancher:/var/lib/rancher \
  --privileged \
  rancher/rancher:latest

As of Rancher v2.5, privileged access is required.

This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).

note

This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - TCP and UDP Load Balancer.

upstream rancher {
    server rancher-server:80;
}

map $http_upgrade $connection_upgrade {
    default Upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    server_name rancher.yourdomain.com;
    ssl_certificate /etc/your_certificate_directory/fullchain.pem;
    ssl_certificate_key /etc/your_certificate_directory/privkey.pem;

    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://rancher;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
        proxy_read_timeout 900s;
        proxy_buffering off;
    }
}

server {
    listen 80;
    server_name rancher.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html index 2ec1bdaef6d..414de4cc328 100644 --- a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html +++ b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html @@ -5,13 +5,13 @@ Enabling the API Audit Log to Record System Events | Rancher Manager - +
Version: v2.6

Enabling the API Audit Log to Record System Events

You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.

You can enable API Auditing during Rancher installation or upgrade.

Enabling API Audit Log​

The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.

API Audit Log Options​

The usage below defines rules about what the audit log should record and what data it should include:

ParameterDescription
AUDIT_LEVEL0 - Disable audit log (default setting).
1 - Log event metadata.
2 - Log event metadata and request body.
3 - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same auditID value.

See Audit Level Logging for a table that displays what each setting logs.
AUDIT_LOG_PATHLog path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log. You can mount the log directory to host.

Usage Example: AUDIT_LOG_PATH=/my/custom/path/
AUDIT_LOG_MAXAGEDefined the maximum number of days to retain old audit log files. Default is 10 days.
AUDIT_LOG_MAXBACKUPDefines the maximum number of audit log files to retain. Default is 10.
AUDIT_LOG_MAXSIZEDefines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M.

Audit Log Levels​

The following table displays what parts of API transactions are logged for each AUDIT_LEVEL setting.

AUDIT_LEVEL SettingRequest MetadataRequest BodyResponse MetadataResponse Body
0
1✓
2✓✓
3✓✓✓✓

Viewing API Audit Logs​

Docker Install​

Share the AUDIT_LOG_PATH directory (Default: /var/log/auditlog) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc.

Kubernetes Install​

Enabling the API Audit Log with the Helm chart install will create a rancher-audit-log sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log.

The rancher-audit-log container is part of the rancher pod in the cattle-system namespace.

CLI​

kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log

Shipping the Audit Log​

You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See Rancher Tools - Logging for details.

Audit Log Samples​

After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction.

Metadata Level​

If you set your AUDIT_LEVEL to 1, Rancher logs the metadata header for every API request, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc.

{
  "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183",
  "requestURI": "/v3/schemas",
  "sourceIPs": ["::1"],
  "user": {
    "name": "user-f4tt2",
    "group": ["system:authenticated"]
  },
  "verb": "GET",
  "stage": "RequestReceived",
  "stageTimestamp": "2018-07-20 10:22:43 +0800"
}

Metadata and Request Body Level​

If you set your AUDIT_LEVEL to 2, Rancher logs the metadata header and body for every API request.

The code sample below depicts an API request, with both its metadata header and body.

{
  "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb",
  "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
  "sourceIPs": ["::1"],
  "user": {
    "name": "user-f4tt2",
    "group": ["system:authenticated"]
  },
  "verb": "PUT",
  "stage": "RequestReceived",
  "stageTimestamp": "2018-07-20 10:28:08 +0800",
  "requestBody": {
    "hostIPC": false,
    "hostNetwork": false,
    "hostPID": false,
    "paused": false,
    "annotations": {},
    "baseType": "workload",
    "containers": [
      {
        "allowPrivilegeEscalation": false,
        "image": "nginx",
        "imagePullPolicy": "Always",
        "initContainer": false,
        "name": "nginx",
        "ports": [
          {
            "containerPort": 80,
            "dnsName": "nginx-nodeport",
            "kind": "NodePort",
            "name": "80tcp01",
            "protocol": "TCP",
            "sourcePort": 0,
            "type": "/v3/project/schemas/containerPort"
          }
        ],
        "privileged": false,
        "readOnly": false,
        "resources": {
          "type": "/v3/project/schemas/resourceRequirements",
          "requests": {},
          "limits": {}
        },
        "restartCount": 0,
        "runAsNonRoot": false,
        "stdin": true,
        "stdinOnce": false,
        "terminationMessagePath": "/dev/termination-log",
        "terminationMessagePolicy": "File",
        "tty": true,
        "type": "/v3/project/schemas/container",
        "environmentFrom": [],
        "capAdd": [],
        "capDrop": [],
        "livenessProbe": null,
        "volumeMounts": []
      }
    ],
    "created": "2018-07-18T07:34:16Z",
    "createdTS": 1531899256000,
    "creatorId": null,
    "deploymentConfig": {
      "maxSurge": 1,
      "maxUnavailable": 0,
      "minReadySeconds": 0,
      "progressDeadlineSeconds": 600,
      "revisionHistoryLimit": 10,
      "strategy": "RollingUpdate"
    },
    "deploymentStatus": {
      "availableReplicas": 1,
      "conditions": [
        {
          "lastTransitionTime": "2018-07-18T07:34:38Z",
          "lastTransitionTimeTS": 1531899278000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "Deployment has minimum availability.",
          "reason": "MinimumReplicasAvailable",
          "status": "True",
          "type": "Available"
        },
        {
          "lastTransitionTime": "2018-07-18T07:34:16Z",
          "lastTransitionTimeTS": 1531899256000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
          "reason": "NewReplicaSetAvailable",
          "status": "True",
          "type": "Progressing"
        }
      ],
      "observedGeneration": 2,
      "readyReplicas": 1,
      "replicas": 1,
      "type": "/v3/project/schemas/deploymentStatus",
      "unavailableReplicas": 0,
      "updatedReplicas": 1
    },
    "dnsPolicy": "ClusterFirst",
    "id": "deployment:default:nginx",
    "labels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    },
    "name": "nginx",
    "namespaceId": "default",
    "projectId": "c-bcz5t:p-fdr4s",
    "publicEndpoints": [
      {
        "addresses": ["10.64.3.58"],
        "allNodes": true,
        "ingressId": null,
        "nodeId": null,
        "podId": null,
        "port": 30917,
        "protocol": "TCP",
        "serviceId": "default:nginx-nodeport",
        "type": "publicEndpoint"
      }
    ],
    "restartPolicy": "Always",
    "scale": 1,
    "schedulerName": "default-scheduler",
    "selector": {
      "matchLabels": {
        "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
      },
      "type": "/v3/project/schemas/labelSelector"
    },
    "state": "active",
    "terminationGracePeriodSeconds": 30,
    "transitioning": "no",
    "transitioningMessage": "",
    "type": "deployment",
    "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
    "workloadAnnotations": {
      "deployment.kubernetes.io/revision": "1",
      "field.cattle.io/creatorId": "user-f4tt2"
    },
    "workloadLabels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    },
    "scheduling": {
      "node": {}
    },
    "description": "my description",
    "volumes": []
  }
}

Metadata, Request Body, and Response Body Level​

If you set your AUDIT_LEVEL to 3, Rancher logs:

  • The metadata header and body for every API request.
  • The metadata header and body for every API response.

Request​

The code sample below depicts an API request, with both its metadata header and body.

{
  "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
  "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
  "sourceIPs": ["::1"],
  "user": {
    "name": "user-f4tt2",
    "group": ["system:authenticated"]
  },
  "verb": "PUT",
  "stage": "RequestReceived",
  "stageTimestamp": "2018-07-20 10:33:06 +0800",
  "requestBody": {
    "hostIPC": false,
    "hostNetwork": false,
    "hostPID": false,
    "paused": false,
    "annotations": {},
    "baseType": "workload",
    "containers": [
      {
        "allowPrivilegeEscalation": false,
        "image": "nginx",
        "imagePullPolicy": "Always",
        "initContainer": false,
        "name": "nginx",
        "ports": [
          {
            "containerPort": 80,
            "dnsName": "nginx-nodeport",
            "kind": "NodePort",
            "name": "80tcp01",
            "protocol": "TCP",
            "sourcePort": 0,
            "type": "/v3/project/schemas/containerPort"
          }
        ],
        "privileged": false,
        "readOnly": false,
        "resources": {
          "type": "/v3/project/schemas/resourceRequirements",
          "requests": {},
          "limits": {}
        },
        "restartCount": 0,
        "runAsNonRoot": false,
        "stdin": true,
        "stdinOnce": false,
        "terminationMessagePath": "/dev/termination-log",
        "terminationMessagePolicy": "File",
        "tty": true,
        "type": "/v3/project/schemas/container",
        "environmentFrom": [],
        "capAdd": [],
        "capDrop": [],
        "livenessProbe": null,
        "volumeMounts": []
      }
    ],
    "created": "2018-07-18T07:34:16Z",
    "createdTS": 1531899256000,
    "creatorId": null,
    "deploymentConfig": {
      "maxSurge": 1,
      "maxUnavailable": 0,
      "minReadySeconds": 0,
      "progressDeadlineSeconds": 600,
      "revisionHistoryLimit": 10,
      "strategy": "RollingUpdate"
    },
    "deploymentStatus": {
      "availableReplicas": 1,
      "conditions": [
        {
          "lastTransitionTime": "2018-07-18T07:34:38Z",
          "lastTransitionTimeTS": 1531899278000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "Deployment has minimum availability.",
          "reason": "MinimumReplicasAvailable",
          "status": "True",
          "type": "Available"
        },
        {
          "lastTransitionTime": "2018-07-18T07:34:16Z",
          "lastTransitionTimeTS": 1531899256000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
          "reason": "NewReplicaSetAvailable",
          "status": "True",
          "type": "Progressing"
        }
      ],
      "observedGeneration": 2,
      "readyReplicas": 1,
      "replicas": 1,
      "type": "/v3/project/schemas/deploymentStatus",
      "unavailableReplicas": 0,
      "updatedReplicas": 1
    },
    "dnsPolicy": "ClusterFirst",
    "id": "deployment:default:nginx",
    "labels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    },
    "name": "nginx",
    "namespaceId": "default",
    "projectId": "c-bcz5t:p-fdr4s",
    "publicEndpoints": [
      {
        "addresses": ["10.64.3.58"],
        "allNodes": true,
        "ingressId": null,
        "nodeId": null,
        "podId": null,
        "port": 30917,
        "protocol": "TCP",
        "serviceId": "default:nginx-nodeport",
        "type": "publicEndpoint"
      }
    ],
    "restartPolicy": "Always",
    "scale": 1,
    "schedulerName": "default-scheduler",
    "selector": {
      "matchLabels": {
        "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
      },
      "type": "/v3/project/schemas/labelSelector"
    },
    "state": "active",
    "terminationGracePeriodSeconds": 30,
    "transitioning": "no",
    "transitioningMessage": "",
    "type": "deployment",
    "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
    "workloadAnnotations": {
      "deployment.kubernetes.io/revision": "1",
      "field.cattle.io/creatorId": "user-f4tt2"
    },
    "workloadLabels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    },
    "scheduling": {
      "node": {}
    },
    "description": "my decript",
    "volumes": []
  }
}

Response​

The code sample below depicts an API response, with both its metadata header and body.

{
  "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
  "responseStatus": "200",
  "stage": "ResponseComplete",
  "stageTimestamp": "2018-07-20 10:33:06 +0800",
  "responseBody": {
    "actionLinks": {
      "pause": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=pause",
      "resume": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=resume",
      "rollback": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=rollback"
    },
    "annotations": {},
    "baseType": "workload",
    "containers": [
      {
        "allowPrivilegeEscalation": false,
        "image": "nginx",
        "imagePullPolicy": "Always",
        "initContainer": false,
        "name": "nginx",
        "ports": [
          {
            "containerPort": 80,
            "dnsName": "nginx-nodeport",
            "kind": "NodePort",
            "name": "80tcp01",
            "protocol": "TCP",
            "sourcePort": 0,
            "type": "/v3/project/schemas/containerPort"
          }
        ],
        "privileged": false,
        "readOnly": false,
        "resources": {
          "type": "/v3/project/schemas/resourceRequirements"
        },
        "restartCount": 0,
        "runAsNonRoot": false,
        "stdin": true,
        "stdinOnce": false,
        "terminationMessagePath": "/dev/termination-log",
        "terminationMessagePolicy": "File",
        "tty": true,
        "type": "/v3/project/schemas/container"
      }
    ],
    "created": "2018-07-18T07:34:16Z",
    "createdTS": 1531899256000,
    "creatorId": null,
    "deploymentConfig": {
      "maxSurge": 1,
      "maxUnavailable": 0,
      "minReadySeconds": 0,
      "progressDeadlineSeconds": 600,
      "revisionHistoryLimit": 10,
      "strategy": "RollingUpdate"
    },
    "deploymentStatus": {
      "availableReplicas": 1,
      "conditions": [
        {
          "lastTransitionTime": "2018-07-18T07:34:38Z",
          "lastTransitionTimeTS": 1531899278000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "Deployment has minimum availability.",
          "reason": "MinimumReplicasAvailable",
          "status": "True",
          "type": "Available"
        },
        {
          "lastTransitionTime": "2018-07-18T07:34:16Z",
          "lastTransitionTimeTS": 1531899256000,
          "lastUpdateTime": "2018-07-18T07:34:38Z",
          "lastUpdateTimeTS": 1531899278000,
          "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
          "reason": "NewReplicaSetAvailable",
          "status": "True",
          "type": "Progressing"
        }
      ],
      "observedGeneration": 2,
      "readyReplicas": 1,
      "replicas": 1,
      "type": "/v3/project/schemas/deploymentStatus",
      "unavailableReplicas": 0,
      "updatedReplicas": 1
    },
    "dnsPolicy": "ClusterFirst",
    "hostIPC": false,
    "hostNetwork": false,
    "hostPID": false,
    "id": "deployment:default:nginx",
    "labels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    },
    "links": {
      "remove": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
      "revisions": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/revisions",
      "self": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
      "update": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
      "yaml": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/yaml"
    },
    "name": "nginx",
    "namespaceId": "default",
    "paused": false,
    "projectId": "c-bcz5t:p-fdr4s",
    "publicEndpoints": [
      {
        "addresses": ["10.64.3.58"],
        "allNodes": true,
        "ingressId": null,
        "nodeId": null,
        "podId": null,
        "port": 30917,
        "protocol": "TCP",
        "serviceId": "default:nginx-nodeport"
      }
    ],
    "restartPolicy": "Always",
    "scale": 1,
    "schedulerName": "default-scheduler",
    "selector": {
      "matchLabels": {
        "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
      },
      "type": "/v3/project/schemas/labelSelector"
    },
    "state": "active",
    "terminationGracePeriodSeconds": 30,
    "transitioning": "no",
    "transitioningMessage": "",
    "type": "deployment",
    "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
    "workloadAnnotations": {
      "deployment.kubernetes.io/revision": "1",
      "field.cattle.io/creatorId": "user-f4tt2"
    },
    "workloadLabels": {
      "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
    }
  }
}
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html index 240cde3f64a..f27f9795b73 100644 --- a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html +++ b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html @@ -5,13 +5,13 @@ Opening Ports with firewalld | Rancher Manager - +
Version: v2.6

Opening Ports with firewalld

We recommend disabling firewalld. For Kubernetes 1.19.x and higher, firewalld must be turned off.

Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm.

For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller:

Chain INPUT (policy ACCEPT)
target     prot opt source               destination
ACCEPT     all  --  anywhere             anywhere             state RELATED,ESTABLISHED
ACCEPT     icmp --  anywhere             anywhere
ACCEPT     all  --  anywhere             anywhere
ACCEPT     tcp  --  anywhere             anywhere             state NEW tcp dpt:ssh
REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination
REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination

You can check the default firewall rules with this command:

sudo iptables --list

This section describes how to use firewalld to apply the firewall port rules for nodes in a high-availability Rancher server cluster.

Prerequisite​

Install v7.x or later ofvfirewalld:

yum install firewalld
systemctl start firewalld
systemctl enable firewalld

Applying Firewall Port Rules​

In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:

firewall-cmd --permanent --add-port=22/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=2379/tcp
firewall-cmd --permanent --add-port=2380/tcp
firewall-cmd --permanent --add-port=6443/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp

If your Rancher server nodes have separate roles, use the following commands based on the role of the node:

# For etcd nodes, run the following commands:
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=2379/tcp
firewall-cmd --permanent --add-port=2380/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp

# For control plane nodes, run the following commands:
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=6443/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp

# For worker nodes, run the following commands:
firewall-cmd --permanent --add-port=22/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=2376/tcp
firewall-cmd --permanent --add-port=8472/udp
firewall-cmd --permanent --add-port=9099/tcp
firewall-cmd --permanent --add-port=10250/tcp
firewall-cmd --permanent --add-port=10254/tcp
firewall-cmd --permanent --add-port=30000-32767/tcp
firewall-cmd --permanent --add-port=30000-32767/udp

After the firewall-cmd commands have been run on a node, use the following command to enable the firewall rules:

firewall-cmd --reload

Result: The firewall is updated so that Helm can communicate with the Rancher server nodes.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html index 188c55ce03d..acde8bb448a 100644 --- a/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html +++ b/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html @@ -5,13 +5,13 @@ Tuning etcd for Large Installations | Rancher Manager - +
Version: v2.6

Tuning etcd for Large Installations

When running larger Rancher installations with 15 or more clusters it is recommended to increase the default keyspace for etcd from the default 2GB. The maximum setting is 8GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval.

The etcd data set is automatically cleaned up on a five minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see mvcc: database space exceeded errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the quota-backend-bytes setting on the etcd servers.

Example: This snippet of the RKE cluster.yml file increases the keyspace size to 5GB​

# RKE cluster.yml
---
services:
  etcd:
    extra_args:
      quota-backend-bytes: 5368709120

Scaling etcd disk performance​

You can follow the recommendations from the etcd docs on how to tune the disk priority on the host.

Additionally, to reduce IO contention on the disks for etcd, you can use a dedicated device for the data and wal directory. Based on etcd best practices, mirroring RAID configurations are unnecessary because etcd replicates data between the nodes in the cluster. You can use striping RAID configurations to increase available IOPS.

To implement this solution in an RKE cluster, the /var/lib/etcd/data and /var/lib/etcd/wal directories will need to have disks mounted and formatted on the underlying host. In the extra_args directive of the etcd service, you must include the wal_dir directory. Without specifying the wal_dir, etcd process will try to manipulate the underlying wal mount with insufficient permissions.

# RKE cluster.yml
---
services:
  etcd:
    extra_args:
      data-dir: '/var/lib/rancher/etcd/data/'
      wal-dir: '/var/lib/rancher/etcd/wal/wal_dir'
    extra_binds:
      - '/var/lib/etcd/data:/var/lib/rancher/etcd/data'
      - '/var/lib/etcd/wal:/var/lib/rancher/etcd/wal'
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.html b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.html index dd706b9498a..7f4a29b47ee 100644 --- a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.html +++ b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/continuous-delivery.html @@ -5,13 +5,13 @@ Continuous Delivery | Rancher Manager - +
Version: v2.6

Continuous Delivery

As of Rancher v2.5, Fleet comes preinstalled in Rancher, and as of Rancher v2.6, Fleet can no longer be fully disabled. However, the Fleet feature for GitOps continuous delivery may be disabled using the continuous-delivery feature flag.

To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

Environment Variable KeyDefault ValueDescription
continuous-deliverytrueThis flag disables the GitOps continuous delivery feature of Fleet.

If Fleet was disabled in Rancher v2.5.x, it will become enabled if Rancher is upgraded to v2.6.x. Only the continuous delivery part of Fleet can be disabled. When continuous-delivery is disabled, the gitjob deployment is no longer deployed into the Rancher server's local cluster, and continuous-delivery is not shown in the Rancher UI.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html index 197d0af8182..9312701e3dd 100644 --- a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html +++ b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html @@ -5,13 +5,13 @@ UI for Istio Virtual Services and Destination Rules | Rancher Manager - +
Version: v2.6

UI for Istio Virtual Services and Destination Rules

This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.

Prerequisite: Turning on this feature does not enable Istio. A cluster administrator needs to enable Istio for the cluster in order to use the feature.

To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

Environment Variable KeyDefault ValueStatusAvailable as of
istio-virtual-service-uifalseExperimentalv2.3.0
istio-virtual-service-uitrueGAv2.3.2

About this Feature​

A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.

When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use kubectl to manage traffic with Istio.

The feature enables two UI tabs: one tab for Virtual Services and another for Destination Rules.

  • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the Istio documentation.
  • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the Istio documentation.

To see these tabs,

  1. Click ☰ > Cluster Management.
  2. Go to the cluster where Istio is installed and click Explore.
  3. In the left navigation bar, click Istio.
  4. You will see tabs for Kiali and Jaeger. From the left navigation bar, you can view and configure Virtual Services and Destination Rules.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html index 91a38d8bbe1..a4df8db27b3 100644 --- a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html +++ b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html @@ -5,14 +5,14 @@ Running on ARM64 (Experimental) | Rancher Manager - +
Version: v2.6

Running on ARM64 (Experimental)

caution

Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment.

The following options are available when using an ARM64 platform:

  • Running Rancher on ARM64 based node(s)

    • Only for Docker Install. Please note that the following installation command replaces the examples found in the Docker Install link:
    # In the last line `rancher/rancher:vX.Y.Z`, be certain to replace "X.Y.Z" with a released version in which ARM64 builds exist. For  example, if your matching version is v2.5.8, you would fill in this line with `rancher/rancher:v2.5.8`.
    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:vX.Y.Z
note

To check if your specific released version is compatible with the ARM64 architecture, you may navigate to your version's release notes in the following two ways:

  • Create custom cluster and adding ARM64 based node(s)
    • Kubernetes cluster version must be 1.12 or higher
    • CNI Network Provider must be Flannel
  • Importing clusters that contain ARM64 based nodes
    • Kubernetes cluster version must be 1.12 or higher

Please see Cluster Options how to configure the cluster options.

The following features are not tested:

  • Monitoring, alerts, notifiers, pipelines and logging
  • Launching apps from the catalog
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html index e2a3cb9f157..243b5ba6088 100644 --- a/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html +++ b/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html @@ -5,13 +5,13 @@ Allow Unsupported Storage Drivers | Rancher Manager - +
Version: v2.6

Allow Unsupported Storage Drivers

This feature allows you to use types for storage providers and provisioners that are not enabled by default.

To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

Environment Variable KeyDefault ValueDescription
unsupported-storage-driversfalseThis feature enables types for storage providers and provisioners that are not enabled by default.

Types for Persistent Volume Plugins that are Enabled by Default​

Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

NamePlugin
Amazon EBS Diskaws-ebs
AzureFileazure-file
AzureDiskazure-disk
Google Persistent Diskgce-pd
Longhornflex-volume-longhorn
VMware vSphere Volumevsphere-volume
Locallocal
Network File Systemnfs
hostPathhost-path

Types for StorageClass that are Enabled by Default​

Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

NamePlugin
Amazon EBS Diskaws-ebs
AzureFileazure-file
AzureDiskazure-disk
Google Persistent Diskgce-pd
Longhornflex-volume-longhorn
VMware vSphere Volumevsphere-volume
Locallocal
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html index a34ff9b8ee3..12bc5961e23 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html @@ -5,13 +5,13 @@ Rendering the Helm Template in an Air-Gapped Environment | Rancher Manager - +
Version: v2.6

Rendering the Helm Template in an Air-Gapped Environment

note

These instructions assume you have already followed the instructions for a Kubernetes upgrade on this page, including the prerequisites, up until step 3. Upgrade Rancher.

Rancher Helm Template Options​

Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

Based on the choice you made during installation, complete one of the procedures below.

PlaceholderDescription
<VERSION>The version number of the output tarball.
<RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
<REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
<CERTMANAGER_VERSION>Cert-manager version running on k8s cluster.

Option A: Default Self-signed Certificate​

helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set certmanager.version=<CERTMANAGER_VERSION> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

Option B: Certificates from Files using Kubernetes Secrets​

helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set ingress.tls.source=secret \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set ingress.tls.source=secret \
    --set privateCA=true \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

Apply the Rendered Templates​

Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.

Use kubectl to apply the rendered manifests.

kubectl -n cattle-system apply -R -f ./rancher

Verify the Upgrade

Log into Rancher to confirm that the upgrade succeeded.

tip

Having network issues following upgrade?

See Restoring Cluster Networking.

Known Upgrade Issues

A list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html index 7ccd243446d..48b22cd6016 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html @@ -5,13 +5,13 @@ Installing Rancher on Azure Kubernetes Service | Rancher Manager - +
Version: v2.6

Installing Rancher on Azure Kubernetes Service

This page covers how to install Rancher on Microsoft's Azure Kubernetes Service (AKS).

The guide uses command line tools to provision an AKS cluster with an ingress. If you prefer to provision your cluster using the Azure portal, refer to the official documentation.

If you already have an AKS Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

Prerequisites​

caution

Deploying to Microsoft Azure will incur charges.

  • Microsoft Azure Account: A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes.
  • Microsoft Azure Subscription: Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet.
  • Micsoroft Azure Tenant: Use this link and follow instructions to create a Microsoft Azure tenant.
  • Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to this section
  • When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on Azure load balancer limitations.

1. Prepare your Workstation​

Install the following command line tools on your workstation:

2. Create a Resource Group​

After installing the CLI, you will need to log in with your Azure account.

az login

Create a resource group to hold all relevant resources for your cluster. Use a location that applies to your use case.

az group create --name rancher-rg --location eastus

3. Create the AKS Cluster​

To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to this article for available sizes and options. When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

note

If the version of Kubernetes is updated to v1.22 or later, the version of ingress-nginx would also need to be updated.

az aks create \
  --resource-group rancher-rg \
  --name rancher-server \
  --kubernetes-version <VERSION> \
  --node-count 3 \
  --node-vm-size Standard_D2_v3

The cluster will take some time to be deployed.

4. Get Access Credentials​

After the cluster is deployed, get the access credentials.

az aks get-credentials --resource-group rancher-rg --name rancher-server

This command merges your cluster's credentials into the existing kubeconfig and allows kubectl to interact with the cluster.

5. Install an Ingress​

The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription.

The following command installs an nginx-ingress-controller with a Kubernetes load balancer service.

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
  ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --set controller.service.type=LoadBalancer \
  --version 4.0.18 \
  --create-namespace

6. Get Load Balancer IP​

To get the address of the load balancer, run:

kubectl get service ingress-nginx-controller --namespace=ingress-nginx

The result should look similar to the following:

NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)
 AGE
ingress-nginx-controller   LoadBalancer   10.0.116.18    40.31.180.83   80:31229/TCP,443:31050/TCP
 67s

Save the EXTERNAL-IP.

7. Set up DNS​

External traffic to the Rancher server will need to be directed at the load balancer you created.

Set up a DNS to point at the EXTERNAL-IP that you saved. This DNS will be used as the Rancher server URL.

There are many valid ways to set up the DNS. For help, refer to the Azure DNS documentation

8. Install the Rancher Helm Chart​

Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

New in v2.6.7

When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:

--set ingress.ingressClassName=nginx

Refer here for the Helm install command for your chosen certificate option.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html index 8582232ddc4..3e32e2a5745 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html @@ -5,13 +5,13 @@ Installing Rancher on Amazon EKS | Rancher Manager - +
Version: v2.6

Installing Rancher on Amazon EKS

This page covers two ways to install Rancher on EKS.

The first is a guide for deploying the Rancher server on an EKS cluster using CloudFormation. This guide was created in collaboration with Amazon Web Services to show how to deploy Rancher following best practices.

The second is a guide for installing an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.

If you already have an EKS Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

Automated Quickstart using AWS Best Practices​

Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS cluster following AWS best practices. The deployment guide is here.

The quick start guide provides three options for deploying Rancher on EKS:

  • Deploy Rancher into a new VPC and new Amazon EKS cluster. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, Amazon EKS cluster, and other infrastructure components. It then deploys Rancher into this new EKS cluster.
  • Deploy Rancher into an existing VPC and a new Amazon EKS cluster. This option provisions Rancher in your existing AWS infrastructure.
  • Deploy Rancher into an existing VPC and existing Amazon EKS cluster. This option provisions Rancher in your existing AWS infrastructure.

Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon EKS cluster using default parameters builds the following Rancher environment in the AWS Cloud:

  • A highly available architecture that spans three Availability Zones.*
  • A VPC configured with public and private subnets, according to AWS best practices, to provide you with your own virtual network on AWS.*
  • In the public subnets:
    • Managed network address translation (NAT) gateways to allow outbound internet access for resources.*
    • Linux bastion hosts in an Auto Scaling group to allow inbound Secure Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets.*
  • In the private subnets:
    • Kubernetes nodes in an Auto Scaling group.*
    • A Network Load Balancer (not shown) for accessing the Rancher console.
  • Rancher deployment using AWS Systems Manager automation.
  • Amazon EKS service for the EKS cluster, which provides the Kubernetes control plane.*
  • An Amazon Route 53 DNS record for accessing the Rancher deployment.

* The CloudFormation template that deploys the Quick Start into an existing Amazon EKS cluster skips the components marked by asterisks and prompts you for your existing VPC configuration.

Creating an EKS Cluster for the Rancher Server​

In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.

Prerequisites:
  • You should already have an AWS account.
  • It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface.
  • The IAM user needs the minimum IAM policies described in the official eksctl documentation.

1. Prepare your Workstation​

Install the following command line tools on your workstation:

2. Configure the AWS CLI​

To configure the AWS CLI, run the following command:

aws configure

Then enter the following values:

ValueDescription
AWS Access Key IDThe access key credential for the IAM user with EKS permissions.
AWS Secret Access KeyThe secret key credential for the IAM user with EKS permissions.
Default region nameAn AWS region where the cluster nodes will be located.
Default output formatEnter json.

3. Create the EKS Cluster​

To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

Note: If the version of Kubernetes is updated to v1.22 or later, the version of ingress-nginx would also need to be updated.

eksctl create cluster \
  --name rancher-server \
  --version <VERSION> \
  --region us-west-2 \
  --nodegroup-name ranchernodes \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 4 \
  --managed

The cluster will take some time to be deployed with CloudFormation.

4. Test the Cluster​

To test the cluster, run:

eksctl get cluster

The result should look like the following:

eksctl get cluster
2021-03-18 15:09:35 [ℹ]  eksctl version 0.40.0
2021-03-18 15:09:35 [ℹ]  using region us-west-2
NAME        REGION      EKSCTL CREATED
rancher-server-cluster      us-west-2   True

5. Install an Ingress​

The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.

The following command installs an nginx-ingress-controller with a LoadBalancer service. This will result in an ELB (Elastic Load Balancer) in front of NGINX:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
  ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --set controller.service.type=LoadBalancer \
  --version 4.0.18 \
  --create-namespace

6. Get Load Balancer IP​

To get the address of the load balancer, run:

kubectl get service ingress-nginx-controller --namespace=ingress-nginx

The result should look similar to the following:

NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP                                                              PORT(S)
 AGE
ingress-nginx-controller   LoadBalancer   10.100.90.18   a904a952c73bf4f668a17c46ac7c56ab-962521486.us-west-2.elb.amazonaws.com   80:31229/TCP,443:31050/TCP
 27m

Save the EXTERNAL-IP.

7. Set up DNS​

External traffic to the Rancher server will need to be directed at the load balancer you created.

Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.

There are many valid ways to set up the DNS. For help, refer to the AWS documentation on routing traffic to an ELB load balancer.

8. Install the Rancher Helm Chart​

Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

New in v2.6.7

When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:

--set ingress.ingressClassName=nginx

Refer here for the Helm install command for your chosen certificate option.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html index eaaa930c664..8541be173c1 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html @@ -5,13 +5,13 @@ Installing Rancher on a Google Kubernetes Engine Cluster | Rancher Manager - +
Version: v2.6

Installing Rancher on a Google Kubernetes Engine Cluster

In this section, you'll learn how to install Rancher using Google Kubernetes Engine.

If you already have a GKE Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

Prerequisites​

  • You will need a Google account.
  • You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit General guide to the console.
  • You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to this section.

1. Enable the Kubernetes Engine API​

Take the following steps to enable the Kubernetes Engine API:

  1. Visit the Kubernetes Engine page in the Google Cloud Console.
  2. Create or select a project.
  3. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes.
  4. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the Google Cloud documentation.

2. Open the Cloud Shell​

Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the gcloud command-line tool and kubectl command-line tool. The gcloud tool provides the primary command-line interface for Google Cloud, and kubectl provides the primary command-line interface for running commands against Kubernetes clusters.

The following sections describe how to launch the cloud shell from the Google Cloud Console or from your local workstation.

Cloud Shell​

To launch the shell from the Google Cloud Console, go to the upper-right corner of the console and click the terminal button. When hovering over the button, it is labeled Activate Cloud Shell.

Local Shell​

To install gcloud and kubectl, perform the following steps:

  1. Install the Cloud SDK by following these steps. The Cloud SDK includes the gcloud command-line tool. The steps vary based on your OS.

  2. After installing Cloud SDK, install the kubectl command-line tool by running the following command:

    gcloud components install kubectl

    In a later step, kubectl will be configured to use the new GKE cluster.

  3. Install Helm 3 if it is not already installed.

  4. Enable Helm experimental support for OCI images with the HELM_EXPERIMENTAL_OCI variable. Add the following line to ~/.bashrc (or ~/.bash_profile in macOS, or wherever your shell stores environment variables):

    export HELM_EXPERIMENTAL_OCI=1

  5. Run the following command to load your updated .bashrc file:

    source ~/.bashrc

    If you are running macOS, use this command:

    source ~/.bash_profile

3. Configure the gcloud CLI​

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID, zone, and region.

  1. Run gcloud init and follow the directions:

    gcloud init

    If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

    gcloud init --console-only

  2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created.

4. Confirm that gcloud is configured correctly​

Run:

gcloud config list

The output should resemble the following:

[compute]
region = us-west1 # Your chosen region
zone = us-west1-b # Your chosen zone
[core]
account = <Your email>
disable_usage_reporting = True
project = <Your project ID>

Your active configuration is: [default]

5. Create a GKE Cluster​

The following command creates a three-node cluster.

Replace cluster-name with the name of your new cluster.

When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

Note: If the version of Kubernetes is updated to v1.22 or later, the version of ingress-nginx would also need to be updated.

gcloud container clusters create cluster-name --num-nodes=3 --cluster-version=<VERSION>

6. Get Authentication Credentials​

After creating your cluster, you need to get authentication credentials to interact with the cluster:

gcloud container clusters get-credentials cluster-name

This command configures kubectl to use the cluster you created.

7. Install an Ingress​

The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.

The following command installs an nginx-ingress-controller with a LoadBalancer service:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm upgrade --install \
  ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --set controller.service.type=LoadBalancer \
  --version 4.0.18 \
  --create-namespace

8. Get the Load Balancer IP​

To get the address of the load balancer, run:

kubectl get service ingress-nginx-controller --namespace=ingress-nginx

The result should look similar to the following:

NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   10.3.244.156   35.233.206.34   80:31876/TCP,443:32497/TCP   81s

Save the EXTERNAL-IP.

9. Set up DNS​

External traffic to the Rancher server will need to be directed at the load balancer you created.

Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.

There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about managing DNS records.

10. Install the Rancher Helm chart​

Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

Use the DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

New in v2.6.7

When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:

--set ingress.ingressClassName=nginx

Refer here for the Helm install command for your chosen certificate option.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html index bb1ed3ac1d0..b079cc4e55b 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html @@ -5,13 +5,13 @@ Rollbacks | Rancher Manager - +
Version: v2.6

Rollbacks

Rolling Back to Rancher v2.5.0+​

To roll back to Rancher v2.5.0+, use the Rancher Backups application and restore Rancher from backup.

Rancher has to be started with the lower/previous version after a rollback.

A restore is performed by creating a Restore custom resource.

Important:

  • Follow the instructions from this page for restoring Rancher on the same cluster where it was backed up from. In order to migrate Rancher to a new cluster, follow the steps to migrate Rancher.

  • While restoring Rancher on the same setup, the Rancher deployment is manually scaled down before the restore starts, then the operator will scale it back up once the restore completes. As a result, Rancher and its UI will be unavailable until the restore is complete. While the UI is unavailable, use the original cluster kubeconfig with the restore YAML file: kubectl create -f restore.yaml.

Scale the Rancher Deployment to 0​

  1. In the upper left corner, click ☰ > local.
  2. From the menu on the left, click Workload.
  3. Under Workload, click on Deployments.
  4. At the top, click on the dropdown to adjust the filter. Select cattle-system as the filter.
  5. Find the row for the rancher deployment and click ⋮ > Edit Config.
  6. Change Replicas to 0.
  7. Scroll to the bottom and click Save.

Create the Restore Custom Resource​

  1. Click ☰ > Cluster Management.

  2. Go to the local cluster and click Explore.

  3. In the left navigation bar, click Rancher Backups > Restore.

    note

    If the Rancher Backups app is not visible, you will need to install it from the Charts page in Apps & Marketplace. Refer here for more information.

  4. Click Create.

  5. Create the Restore with the form or with YAML. For help creating the Restore resource using the online form, refer to the configuration reference and to the examples.

  6. To use the YAML editor, you can click Create > Create from YAML. Enter the Restore YAML. The following is an example Restore custom resource:

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-migration
    spec:
      backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
      encryptionConfigSecretName: encryptionconfig
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: rancher
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com

    For help configuring the Restore, refer to the configuration reference and to the examples.

  7. Click Create.

Result: The backup file is created and updated to the target storage location. The resources are restored in this order:

  1. Custom Resource Definitions (CRDs)
  2. Cluster-scoped resources
  3. Namespaced resources

To check how the restore is progressing, you can check the logs of the operator. Follow these steps to get the logs:

kubectl get pods -n cattle-resources-system
kubectl logs -n cattle-resources-system -f

Roll back to a previous Rancher version​

Rancher can be rolled back using the Helm CLI. To roll back to the previous version:

helm rollback rancher -n cattle-system

If the previous revision is not the intended target, you can specify a revision to roll back to. To see the deployment history:

helm history rancher -n cattle-system

When the target revision is determined, perform the rollback. This example will roll back to revision 3:

helm rollback rancher 3 -n cattle-system

Rolling Back to Rancher v2.2-v2.4+​

To roll back to Rancher before v2.5, follow the procedure detailed here: Restoring Backups — Kubernetes installs Restoring a snapshot of the Rancher server cluster will revert Rancher to the version and state at the time of the snapshot.

For information on how to roll back Rancher installed with Docker, refer to this page.

note

Managed clusters are authoritative for their state. This means restoring the Rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.

Rolling Back to Rancher v2.0-v2.1​

Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved here and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html index 9a4a2eb8641..db3df489dc2 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting the Rancher Server Kubernetes Cluster | Rancher Manager - +
Version: v2.6

Troubleshooting the Rancher Server Kubernetes Cluster

This section describes how to troubleshoot an installation of Rancher on a Kubernetes cluster.

Relevant Namespaces​

Most of the troubleshooting will be done on objects in these 3 namespaces.

  • cattle-system - rancher deployment and pods.
  • ingress-nginx - Ingress controller pods and services.
  • cert-manager - cert-manager pods.

"default backend - 404"​

A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration.

Things to check

Check if Rancher is Running​

Use kubectl to check the cattle-system system namespace and see if the Rancher pods are in a Running state.

kubectl -n cattle-system get pods

NAME                           READY     STATUS    RESTARTS   AGE
pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

If the state is not Running, run a describe on the pod and check the Events.

kubectl -n cattle-system describe pod

...
Events:
  Type     Reason                 Age   From                Message
  ----     ------                 ----  ----                -------
  Normal   Scheduled              11m   default-scheduler   Successfully assigned rancher-784d94f59b-vgqzh to localhost
  Normal   SuccessfulMountVolume  11m   kubelet, localhost  MountVolume.SetUp succeeded for volume "rancher-token-dj4mt"
  Normal   Pulling                11m   kubelet, localhost  pulling image "rancher/rancher:v2.0.4"
  Normal   Pulled                 11m   kubelet, localhost  Successfully pulled image "rancher/rancher:v2.0.4"
  Normal   Created                11m   kubelet, localhost  Created container
  Normal   Started                11m   kubelet, localhost  Started container

Check the Rancher Logs​

Use kubectl to list the pods.

kubectl -n cattle-system get pods

NAME                           READY     STATUS    RESTARTS   AGE
pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

Use kubectl and the pod name to list the logs from the pod.

kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh

Cert CN is "Kubernetes Ingress Controller Fake Certificate"​

Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert.

note

If you are using LetsEncrypt to issue certs, it can sometimes take a few minutes to issue the cert.

Checking for issues with cert-manager issued certs (Rancher Generated or LetsEncrypt)​

cert-manager has 3 parts.

  • cert-manager pod in the cert-manager namespace.
  • Issuer object in the cattle-system namespace.
  • Certificate object in the cattle-system namespace.

Work backwards and do a kubectl describe on each object and check the events. You can track down what might be missing.

For example there is a problem with the Issuer:

kubectl -n cattle-system describe certificate
...
Events:
  Type     Reason          Age                 From          Message
  ----     ------          ----                ----          -------
  Warning  IssuerNotReady  18s (x23 over 19m)  cert-manager  Issuer rancher not ready
kubectl -n cattle-system describe issuer
...
Events:
  Type     Reason         Age                 From          Message
  ----     ------         ----                ----          -------
  Warning  ErrInitIssuer  19m (x12 over 19m)  cert-manager  Error initializing issuer: secret "tls-rancher" not found
  Warning  ErrGetKeyPair  9m (x16 over 19m)   cert-manager  Error getting keypair for CA issuer: secret "tls-rancher" not found

Checking for Issues with Your Own SSL Certs​

Your certs get applied directly to the Ingress object in the cattle-system namespace.

Check the status of the Ingress object and see if its ready.

kubectl -n cattle-system describe ingress

If its ready and the SSL is still not working you may have a malformed cert or secret.

Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.

kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller
...
W0705 23:04:58.240571       7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found

No matches for kind "Issuer"​

The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown:

Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1"

Install cert-manager and try installing Rancher again.

Canal Pods show READY 2/3​

The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups.

Once the network issue is resolved, the canal pods should timeout and restart to establish their connections.

nginx-ingress-controller Pods show RESTARTS​

The most common cause of this issue is the canal pods have failed to establish the overlay network. See canal Pods show READY 2/3 for troubleshooting.

Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)​

Some causes of this error include:

  • User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command docker ps:
$ ssh user@server
user@server$ docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES

See Manage Docker as a non-root user how to set this up properly.

  • When using RedHat/CentOS as operating system, you cannot use the user root to connect to the nodes because of Bugzilla #1527565. You will need to add a separate user and configure it to access the Docker socket. See Manage Docker as a non-root user how to set this up properly.

  • SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using sshd -V on the host you are connecting to, or using netcat:

$ nc xxx.xxx.xxx.xxx 22
SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10

Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: no key found​

The key file specified as ssh_key_path cannot be accessed. Make sure that you specified the private key file (not the public key, .pub), and that the user that is running the rke command can access the private key file.

Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain​

The key file specified as ssh_key_path is not correct for accessing the node. Double-check if you specified the correct ssh_key_path for the node and if you specified the correct user to connect with.

Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: cannot decode encrypted private keys​

If you want to use encrypted private keys, you should use ssh-agent to load your keys with your passphrase. If the SSH_AUTH_SOCK environment variable is found in the environment where the rke command is run, it will be used automatically to connect to the node.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?​

The node is not reachable on the configured address and port.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html index f95b534e21b..79b476c2e64 100644 --- a/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html +++ b/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html @@ -5,13 +5,13 @@ Upgrades | Rancher Manager - +
Version: v2.6

Upgrades

The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air-gapped installs with Helm.

For the instructions to upgrade Rancher installed with Docker, refer to this page.

To upgrade the components in your Kubernetes cluster, or the definition of the Kubernetes services or add-ons, refer to the upgrade documentation for RKE, the Rancher Kubernetes Engine.

Prerequisites​

Access to kubeconfig​

Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.

If you installed Kubernetes with RKE, the config will have been created in the directory you ran rke up in.

The kubeconfig can also be manually targeted for the intended cluster with the --kubeconfig tag (see: https://helm.sh/docs/helm/helm/)

Review Known Issues​

Review the list of known issues for each Rancher version, which can be found in the release notes on GitHub and on the Rancher forums.

Note that upgrades to or from any chart in the rancher-alpha repository aren't supported.

Helm Version​

The upgrade instructions assume you are using Helm 3.

For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. The Helm 2 upgrade page hereprovides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

For air-gapped installs: Populate private registry​

For air-gapped installs only, collect and populate images for the new Rancher server version. Follow the guide to populate your private registry with the images for the Rancher version that you want to upgrade to.

For upgrades from a Rancher server with a hidden local cluster​

If you are upgrading to Rancher v2.5 from a Rancher server that was started with the Helm chart option --add-local=false, you will need to drop that flag when upgrading. Otherwise, the Rancher server will not start. The restricted-admin role can be used to continue restricting access to the local cluster. For more information, see this section.

For upgrades with cert-manager older than 0.8.0​

Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019. Upgrade cert-manager to the latest version by following these instructions.

Upgrade Outline​

Follow the steps to upgrade Rancher server:

1. Back up Your Kubernetes Cluster that is Running Rancher Server​

Use the backup application to back up Rancher.

You'll use the backup as a restore point if something goes wrong during upgrade.

2. Update the Helm chart repository​

  1. Update your local helm repo cache.

    helm repo update

  2. Get the repository name that you used to install Rancher.

    For information about the repos and their differences, see Helm Chart Repositories.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
      Note: Upgrades are not supported to, from, or between Alphas.
    helm repo list

    NAME                   URL
    stable                 https://charts.helm.sh/stable
    rancher-<CHART_REPO>     https://releases.rancher.com/server-charts/<CHART_REPO>
    note

    If you want to switch to a different Helm chart repository, please follow the steps on how to switch repositories. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.

  3. Fetch the latest chart to install Rancher from the Helm chart repository.

    This command will pull down the latest charts and save it in the current directory as a .tgz file.

    helm fetch rancher-<CHART_REPO>/rancher

    You can fetch the chart for the specific version you are upgrading to by adding in the --version= tag. For example:

    helm fetch rancher-<CHART_REPO>/rancher --version=2.6.8

3. Upgrade Rancher​

This section describes how to upgrade normal (Internet-connected) or air-gapped installations of Rancher with Helm.

Air Gap Instructions:

If you are installing Rancher in an air-gapped environment, skip the rest of this page and render the Helm template by following the instructions on this page.

Get the values, which were passed with --set, from the current Rancher Helm chart that is installed.

helm get values rancher -n cattle-system

hostname: rancher.my.org
note

There will be more values that are listed with this command. This is just an example of one of the values.

If you are upgrading cert-manager to the latest version from v1.5 or below, follow the cert-manager upgrade docs to learn how to upgrade cert-manager without needing to perform an uninstall or reinstall of Rancher. Otherwise, follow the steps to upgrade Rancher below.

Steps to Upgrade Rancher​

Upgrade Rancher to the latest version with all your settings.

Take all the values from the previous step and append them to the command using --set key=value:

helm upgrade rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  --set hostname=rancher.my.org
note

The above is an example, there may be more values from the previous step that need to be appended.

Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:

helm get values rancher -n cattle-system -o yaml > values.yaml

helm upgrade rancher rancher-<CHART_REPO>/rancher \
  --namespace cattle-system \
  -f values.yaml \
  --version=2.6.8

4. Verify the Upgrade​

Log into Rancher to confirm that the upgrade succeeded.

tip

Having network issues following upgrade?

See Restoring Cluster Networking.

Known Upgrade Issues​

A list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/installation-requirements/dockershim.html b/getting-started/installation-and-upgrade/installation-requirements/dockershim.html index b43f643591f..138d3b030c4 100644 --- a/getting-started/installation-and-upgrade/installation-requirements/dockershim.html +++ b/getting-started/installation-and-upgrade/installation-requirements/dockershim.html @@ -5,13 +5,13 @@ Dockershim | Rancher Manager - +
Version: v2.6

Dockershim

The Dockershim is the CRI compliant layer between the Kubelet and the Docker daemon. As part of the Kubernetes 1.20 release, the deprecation of the in-tree Dockershim was announced. For more information on the deprecation and its timelines, see the Kubernetes Dockershim Deprecation FAQ.

RKE clusters now support the external Dockershim to continue leveraging Docker as the CRI runtime. We now implement the upstream open source community external Dockershim announced by Mirantis and Docker to ensure RKE clusters can continue to leverage Docker.

RKE2 and K3s clusters use an embedded containerd as a container runtime and are not affected.

To enable the external Dockershim in versions of RKE before 1.24, configure the following option.

enable_cri_dockerd: true

Starting with version 1.24, the above defaults to true.

For users looking to use another container runtime, Rancher has the edge-focused K3s and datacenter-focused RKE2 Kubernetes distributions that use containerd as the default runtime. Imported RKE2 and K3s Kubernetes clusters can then be upgraded and managed through Rancher going forward.

FAQ​


Q: Do I have to upgrade Rancher to get Rancher’s support of the upstream external Dockershim replacement?

A: The upstream support of the Dockershim replacement cri_dockerd begins for RKE in Kubernetes 1.21. You will need to be on a version of Rancher that supports RKE 1.21. See our support matrix for details.


Q: I am currently on RKE with Kubernetes 1.23. What happens when upstream finally removes Dockershim in 1.24?

A: The version of Dockershim in RKE with Kubernetes will continue to work until 1.23. For information on the timeline, see the Kubernetes Dockershim Deprecation FAQ. After this, starting in 1.24, RKE will default to enabling cri_dockerd by default and will continue to do for versions afterwards.


Q: What are my other options if I don’t want to depend on the Dockershim or cri_dockerd?

A: You can use a runtime like containerd with Kubernetes that does not require Dockershim support. RKE2 or K3s are two options for doing this.


Q: If I am already using RKE1 and want to switch to RKE2, what are my migration options?

A: Today, you can stand up a new cluster and migrate workloads to a new RKE2 cluster that uses containerd. Rancher is exploring the possibility of an in-place upgrade path.


Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/installation-requirements/install-docker.html b/getting-started/installation-and-upgrade/installation-requirements/install-docker.html index 52b7135a85c..34337637785 100644 --- a/getting-started/installation-and-upgrade/installation-requirements/install-docker.html +++ b/getting-started/installation-and-upgrade/installation-requirements/install-docker.html @@ -5,13 +5,13 @@ Installing Docker | Rancher Manager - +
Version: v2.6

Installing Docker

Docker is required to be installed on nodes where the Rancher server will be installed with Helm on an RKE cluster or with Docker. Docker is not required for RKE2 or K3s clusters.

There are a couple of options for installing Docker. One option is to refer to the official Docker documentation about how to install Docker on Linux. The steps will vary based on the Linux distribution.

Another option is to use one of Rancher's Docker installation scripts, which are available for most recent versions of Docker.

For example, this command could be used to install Docker 20.10 on Ubuntu:

curl https://releases.rancher.com/install-docker/20.10.sh | sh

Rancher has installation scripts for every version of upstream Docker that Kubernetes supports. To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher's Docker installation scripts.

Note that the following sysctl setting must be applied:

net.bridge.bridge-nf-call-iptables=1
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html b/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html index a45c52fa919..1b1c8d5f0eb 100644 --- a/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html +++ b/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html @@ -5,14 +5,14 @@ Port Requirements | Rancher Manager - +
Version: v2.6

Port Requirements

To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.

Rancher Nodes

The following table lists the ports that need to be open to and from nodes that are running the Rancher server.

The port requirements differ based on the Rancher server architecture.

Rancher can be installed on any Kubernetes cluster. For Rancher installs on a K3s, RKE, or RKE2 Kubernetes cluster, refer to the tabs below. For other Kubernetes distributions, refer to the distribution's documentation for the port requirements for cluster nodes.

Notes:
  • Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example).
  • Kubernetes recommends TCP 30000-32767 for node port services.
  • For firewalls, traffic may need to be enabled within the cluster and pod CIDR.
  • Rancher nodes may also need outbound access to an external S3 location which is used for storing cluster backups (Minio for example).

Ports for Rancher Server Nodes on K3s​

Click to expand

The K3s server needs port 6443 to be accessible by the nodes.

The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.

If you wish to utilize the metrics server, you will need to open port 10250 on each node.

Important:

The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.

The following tables break down the port requirements for inbound and outbound traffic:

Inbound Rules for Rancher Server Nodes
ProtocolPortSourceDescription
TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
TCP443
  • server nodes
  • agent nodes
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
Rancher agent, Rancher UI/API, kubectl
TCP6443K3s server nodesKubernetes API
UDP8472K3s server and agent nodesRequired only for Flannel VXLAN.
TCP10250K3s server and agent nodeskubelet
Outbound Rules for Rancher Nodes
ProtocolPortDestinationDescription
TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
TCP443git.rancher.ioRancher catalog
TCP2376Any node IP from a node created using Node driverDocker daemon TLS port used by Docker Machine
TCP6443Hosted/Imported Kubernetes APIKubernetes API server

Ports for Rancher Server Nodes on RKE​

Click to expand

Typically Rancher is installed on three RKE nodes that all have the etcd, control plane and worker roles.

The following tables break down the port requirements for traffic between the Rancher nodes:

Rules for traffic between Rancher nodes
ProtocolPortDescription
TCP443Rancher agents
TCP2379etcd client requests
TCP2380etcd peer communication
TCP6443Kubernetes apiserver
TCP8443Nginx Ingress's Validating Webhook
UDP8472Canal/Flannel VXLAN overlay networking
TCP9099Canal/Flannel livenessProbe/readinessProbe
TCP10250Metrics server communication with all nodes
TCP10254Ingress controller livenessProbe/readinessProbe

The following tables break down the port requirements for inbound and outbound traffic:

Inbound Rules for Rancher Nodes
ProtocolPortSourceDescription
TCP22RKE CLISSH provisioning of node by RKE
TCP80Load Balancer/Reverse ProxyHTTP traffic to Rancher UI/API
TCP443
  • Load Balancer/Reverse Proxy
  • IPs of all cluster nodes and other API/UI clients
HTTPS traffic to Rancher UI/API
TCP6443Kubernetes API clientsHTTPS traffic to Kubernetes API
Outbound Rules for Rancher Nodes
ProtocolPortDestinationDescription
TCP44335.160.43.145,35.167.242.46,52.33.59.17Rancher catalog (git.rancher.io)
TCP22Any node created using a node driverSSH provisioning of node by node driver
TCP2376Any node created using a node driverDocker daemon TLS port used by node driver
TCP6443Hosted/Imported Kubernetes APIKubernetes API server
TCPProvider dependentPort of the Kubernetes API endpoint in hosted clusterKubernetes API

Ports for Rancher Server Nodes on RKE2​

Click to expand

The RKE2 server needs port 6443 and 9345 to be accessible by other nodes in the cluster.

All nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used.

If you wish to utilize the metrics server, you will need to open port 10250 on each node.

Important:

The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.

Inbound Rules for RKE2 Server Nodes
ProtocolPortSourceDescription
TCP9345RKE2 agent nodesKubernetes API
TCP6443RKE2 agent nodesKubernetes API
UDP8472RKE2 server and agent nodesRequired only for Flannel VXLAN
TCP10250RKE2 server and agent nodeskubelet
TCP2379RKE2 server nodesetcd client port
TCP2380RKE2 server nodesetcd peer port
TCP30000-32767RKE2 server and agent nodesNodePort port range
TCP5473Calico-node pod connecting to typha podRequired when deploying with Calico
HTTP8080Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
HTTPS8443
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
Rancher agent, Rancher UI/API, kubectl. Not needed if you have LB doing TLS termination.

Typically all outbound traffic is allowed.

Ports for Rancher Server in Docker​

Click to expand

The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic:

Inbound Rules for Rancher Node
ProtocolPortSourceDescription
TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
TCP443
  • hosted/registered Kubernetes
  • any source that needs to be able to use the Rancher UI or API
Rancher agent, Rancher UI/API, kubectl
Outbound Rules for Rancher Node
ProtocolPortSourceDescription
TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
TCP443git.rancher.ioRancher catalog
TCP2376Any node IP from a node created using a node driverDocker daemon TLS port used by Docker Machine
TCP6443Hosted/Imported Kubernetes APIKubernetes API server

Downstream Kubernetes Cluster Nodes

Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.

The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different cluster types.

The following diagram depicts the ports that are opened for each cluster type.

Port Requirements for the Rancher Management Plane

Basic Port Requirements

tip

If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in Commonly Used Ports as your port reference instead of the comprehensive tables below.

Ports for Rancher Launched Kubernetes Clusters using Node Pools​

Click to expand

The following table depicts the port requirements for Rancher Launched Kubernetes with nodes created in an Infrastructure Provider.

note

The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.

From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
Rancher Nodes (1)22 TCPgit.rancher.io
2376 TCP
etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
2380 TCP
6443 TCP
8472 UDP
9099 TCP (4)
Control Plane Nodes443 TCP (3)2379 TCP443 TCP
2380 TCP
6443 TCP
8472 UDP
10250 TCP
9099 TCP (4)
10254 TCP (4)
Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
8472 UDP
9099 TCP (4)
10254 TCP (4)
Kubernetes API Clients6443 TCP (5)
Workload Clients or Load Balancer30000-32767 TCP / UDP
(nodeport)
80 TCP (Ingress)
443 TCP (Ingress)
Notes:

1. Nodes running standalone server or Rancher HA deployment.
2. Required to fetch Rancher chart library.
3. Only without external load balancer in front of Rancher.
4. Local traffic to the node itself (not across nodes).
5. Only if Authorized Cluster Endpoints are activated.

Ports for Rancher Launched Kubernetes Clusters using Custom Nodes​

Click to expand

The following table depicts the port requirements for Rancher Launched Kubernetes with Custom Nodes.

From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
Rancher Nodes (1)git.rancher.io
etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
2380 TCP
6443 TCP
8472 UDP
4789 UDP (6)
9099 TCP (4)
Control Plane Nodes443 TCP (3)2379 TCP443 TCP
2380 TCP
6443 TCP
8472 UDP
4789 UDP (6)
10250 TCP
9099 TCP (4)
10254 TCP (4)
Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
8472 UDP
4789 UDP (6)
9099 TCP (4)
10254 TCP (4)
Kubernetes API Clients6443 TCP (5)
Workload Clients or Load Balancer30000-32767 TCP / UDP
(nodeport)
80 TCP (Ingress)
443 TCP (Ingress)
Notes:

1. Nodes running standalone server or Rancher HA deployment.
2. Required to fetch Rancher chart library.
3. Only without external load balancer in front of Rancher.
4. Local traffic to the node itself (not across nodes).
5. Only if Authorized Cluster Endpoints are activated.
6. Only if using Overlay mode on Windows cluster.

Ports for Hosted Kubernetes Clusters​

Click to expand

The following table depicts the port requirements for hosted clusters.

From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
Rancher Nodes (1)Kubernetes API
Endpoint Port (2)		git.rancher.io
8443 TCP
9443 TCP
Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
Kubernetes API ClientsCluster / Provider Specific (6)
Workload ClientCluster / Provider Specific (7)
Notes:

1. Nodes running standalone server or Rancher HA deployment.
2. Only for hosted clusters.
3. Required to fetch Rancher chart library.
4. Only without external load balancer.
5. From worker nodes.
6. For direct access to the Kubernetes API without Rancher.
7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

Ports for Registered Clusters​

note

Registered clusters were called imported clusters before Rancher v2.5.

Click to expand

The following table depicts the port requirements for registered clusters.

From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
Rancher Nodes (1)Kubernetes API
Endpoint Port (2)		git.rancher.io
8443 TCP
9443 TCP
Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
Kubernetes API ClientsCluster / Provider Specific (6)
Workload ClientCluster / Provider Specific (7)
Notes:

1. Nodes running standalone server or Rancher HA deployment.
2. Only for hosted clusters.
3. Required to fetch Rancher chart library.
4. Only without external load balancer.
5. From worker nodes.
6. For direct access to the Kubernetes API without Rancher.
7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

Other Port Considerations

Commonly Used Ports​

These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.

ProtocolPortDescription
TCP22Node driver SSH provisioning
TCP179Calico BGP Port
TCP2376Node driver Docker daemon TLS port
TCP2379etcd client requests
TCP2380etcd peer communication
UDP8472Canal/Flannel VXLAN overlay networking
UDP4789Flannel VXLAN overlay networking on Windows cluster
TCP8443Rancher webhook
TCP9099Canal/Flannel livenessProbe/readinessProbe
TCP9100Default port required by Monitoring to scrape metrics from Linux node-exporters
TCP9443Rancher webhook
TCP9796Default port required by Monitoring to scrape metrics from Windows node-exporters
TCP6783Weave Port
UDP6783-6784Weave UDP Ports
TCP10250Metrics server communication with all nodes API
TCP10254Ingress controller livenessProbe/readinessProbe
TCP/UDP30000-32767NodePort port range

Local Node Traffic​

Ports marked as local traffic (i.e., 9099 TCP) in the above requirements are used for Kubernetes healthchecks (livenessProbe andreadinessProbe). These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.

However, this traffic may be blocked when:

  • You have applied strict host firewall policies on the node.
  • You are using nodes that have multiple interfaces (multihomed).

In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances.

Rancher AWS EC2 Security Group​

When using the AWS EC2 node driver to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called rancher-nodes. The following rules are automatically added to this security group.

TypeProtocolPort RangeSource/DestinationRule Type
SSHTCP220.0.0.0/0Inbound
HTTPTCP800.0.0.0/0Inbound
Custom TCP RuleTCP4430.0.0.0/0Inbound
Custom TCP RuleTCP23760.0.0.0/0Inbound
Custom TCP RuleTCP2379-2380sg-xxx (rancher-nodes)Inbound
Custom UDP RuleUDP4789sg-xxx (rancher-nodes)Inbound
Custom TCP RuleTCP64430.0.0.0/0Inbound
Custom UDP RuleUDP8472sg-xxx (rancher-nodes)Inbound
Custom TCP RuleTCP10250-10252sg-xxx (rancher-nodes)Inbound
Custom TCP RuleTCP10256sg-xxx (rancher-nodes)Inbound
Custom TCP RuleTCP30000-327670.0.0.0/0Inbound
Custom UDP RuleUDP30000-327670.0.0.0/0Inbound
All trafficAllAll0.0.0.0/0Outbound

Opening SUSE Linux Ports​

SUSE Linux may have a firewall that blocks all ports by default. To open the ports needed for adding the host to a custom cluster,

1. SSH into the instance. 1. Start YaST in text mode: ``` sudo yast2 ```
  1. Navigate to Security and Users > Firewall > Zones:public > Ports. To navigate within the interface, follow the instructions here.
  2. To open the required ports, enter them into the TCP Ports and UDP Ports fields. In this example, ports 9796 and 10250 are also opened for monitoring. The resulting fields should look similar to the following:
TCP Ports
22, 80, 443, 2376, 2379, 2380, 6443, 9099, 9796, 10250, 10254, 30000-32767
UDP Ports
8472, 30000-32767
  1. When all required ports are enter, select Accept.

Result: The node has the open ports required to be added to a custom cluster.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html index faf13b7388a..f9ff14d8e4f 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html @@ -5,13 +5,13 @@ Docker Install Commands | Rancher Manager - +
Version: v2.6

Docker Install Commands

The Docker installation is for Rancher users who want to test out Rancher.

Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a docker run command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

The backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using these steps.

For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

Environment Variable KeyEnvironment Variable ValueDescription
CATTLE_SYSTEM_DEFAULT_REGISTRY<REGISTRY.YOURDOMAIN.COM:PORT>Configure Rancher server to always pull from your private registry when provisioning clusters.
CATTLE_SYSTEM_CATALOGbundledConfigure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror.
Do you want to..

Choose from the following options:

Option A: Default Self-Signed Certificate​

Click to expand

If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder.

PlaceholderDescription
<REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.

Privileged access is required.

docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
    --privileged \
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

Option B: Bring Your Own Certificate: Self-Signed​

Click to expand

In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.

Prerequisites:

From a computer with an internet connection, create a self-signed certificate using OpenSSL or another method of your choice.

  • The certificate files must be in PEM format.
  • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the -v flag and provide the path to your certificates to mount them in your container.

PlaceholderDescription
<CERT_DIRECTORY>The path to the directory containing your certificate files.
<FULL_CHAIN.pem>The path to your full certificate chain.
<PRIVATE_KEY.pem>The path to the private key for your certificate.
<CA_CERTS.pem>The path to the certificate authority's certificate.
<REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.

Privileged access is required.

docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
    -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
    -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
    --privileged \
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

Option C: Bring Your Own Certificate: Signed by Recognized CA​

Click to expand

In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.

Prerequisite:

The certificate files must be in PEM format.

After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.

PlaceholderDescription
<CERT_DIRECTORY>The path to the directory containing your certificate files.
<FULL_CHAIN.pem>The path to your full certificate chain.
<PRIVATE_KEY.pem>The path to the private key for your certificate.
<REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.
note

Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.

Privileged access is required.

docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    --no-cacerts \
    -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
    -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
    --privileged
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>
note

If you don't intend to send telemetry data, opt out telemetry during the initial login.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html index dc3803b02b2..641491e5232 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html @@ -5,13 +5,13 @@ 1. Set up Infrastructure and Private Registry | Rancher Manager - +
Version: v2.6

1. Set up Infrastructure and Private Registry

In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private Docker registry that must be available to your Rancher node(s).

An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.

The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to this page.

Rancher can be installed on any Kubernetes cluster. The RKE and K3s Kubernetes infrastructure tutorials below are still included for convenience.

We recommend setting up the following infrastructure for a high-availability installation:

  • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
  • An external database to store the cluster data. PostgreSQL, MySQL, and etcd are supported.
  • A load balancer to direct traffic to the two nodes.
  • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
  • A private Docker registry to distribute Docker images to your machines.

1. Set up Linux Nodes​

These hosts will be disconnected from the internet, but require being able to connect with your private registry.

Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

2. Set up External Datastore​

The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

For a high-availability K3s installation, you will need to set up one of the following external databases:

  • PostgreSQL (certified against versions 10.7 and 11.5)
  • MySQL (certified against version 5.7)
  • etcd (certified against version 3.3.15)

When you install Kubernetes, you will pass in details for K3s to connect to the database.

For an example of one way to set up the database, refer to this tutorial for setting up a MySQL database on Amazon's RDS service.

For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

3. Set up the Load Balancer​

You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

  • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
  • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

For an example showing how to set up an NGINX load balancer, refer to this page.

For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

Important:

Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

4. Set up the DNS Record​

Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

5. Set up a Private Docker Registry​

Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.

In a later step, when you set up your K3s Kubernetes cluster, you will create a private registries configuration file with details from this registry.

If you need help with creating a private registry, please refer to the official Docker documentation.

Next: Collect and Publish Images to your Private Registry​

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html index 886df9268a9..e1dbe3e793c 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html @@ -5,7 +5,7 @@ 3. Install Kubernetes (Skip for Docker Installs) | Rancher Manager - + @@ -15,7 +15,7 @@ Also obtain the K3s install script at 
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

Install K3s on each agent:

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

Note, take care to ensure you replace myserver with the IP or valid DNS of the server and replace mynodetoken with the node-token from the server. The node-token is on the server at /var/lib/rancher/k3s/server/node-token

note

K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gapped networks.

4. Save and Start Using the kubeconfig File​

When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

To use this kubeconfig file,

  1. Install kubectl, a Kubernetes command-line tool.
  2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
  3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: [CERTIFICATE-DATA]
    server: [LOAD-BALANCER-DNS]:6443 # Edit this line
  name: default
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
  user:
    password: [PASSWORD]
    username: admin

Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

Note on Upgrading​

Upgrading an air-gap environment can be accomplished in the following manner:

  1. Download the new air-gap images (tar file) from the releases page for the version of K3s you will be upgrading to. Place the tar in the /var/lib/rancher/k3s/agent/images/ directory on each node. Delete the old tar file.
  2. Copy and replace the old K3s binary in /usr/local/bin on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
  3. Restart the K3s service (if not restarted automatically by installer).
note

The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

Issues or errors?​

See the Troubleshooting page.

Next: Install Rancher​

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html index 9acca06b476..bc0f715b557 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html @@ -5,13 +5,13 @@ 4. Install Rancher | Rancher Manager - +
Version: v2.6

4. Install Rancher

This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

Privileged Access for Rancher​

When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the --privileged option.

Docker Instructions​

If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on this page.

Kubernetes Instructions​

Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

1. Add the Helm Chart Repository​

From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.

  1. If you haven't already, install helm locally on a workstation that has internet access. Note: Refer to the Helm version requirements to choose a version of Helm to install Rancher.

  2. Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
      Note: Upgrades are not supported to, from, or between Alphas.

  3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a .tgz file.

    helm fetch rancher-<CHART_REPO>/rancher

    If you require a specific version of Rancher, you can fetch this with the Helm --version parameter like in the following example:

    helm fetch rancher-stable/rancher --version=v2.4.8

2. Choose your SSL Configuration​

Rancher Server is designed to be secure by default and requires SSL/TLS configuration.

When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.

note

If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

ConfigurationChart optionDescriptionRequires cert-manager
Rancher Generated Self-Signed Certificatesingress.tls.source=rancherUse certificates issued by Rancher's generated CA (self signed)
This is the default and does not need to be added when rendering the Helm template.		yes
Certificates from Filesingress.tls.source=secretUse your own certificate files by creating Kubernetes Secret(s).
This option must be passed when rendering the Rancher Helm template.		no

Helm Chart Options for Air Gap Installations​

When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.

Chart OptionChart ValueDescription
certmanager.version<version>Configure proper Rancher TLS issuer depending of running cert-manager version.
systemDefaultRegistry<REGISTRY.YOURDOMAIN.COM:PORT>Configure Rancher server to always pull from your private registry when provisioning clusters.
useBundledSystemCharttrueConfigure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror.

3. Render the Rancher Helm Template​

Based on the choice your made in 2. Choose your SSL Configuration, complete one of the procedures below.

Option A: Default Self-Signed Certificate​

By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.

note

Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade cert-manager documentation.

1. Add the cert-manager repo​

From a system connected to the internet, add the cert-manager repo to Helm:

helm repo add jetstack https://charts.jetstack.io
helm repo update
2. Fetch the cert-manager chart​

Fetch the latest cert-manager chart available from the Helm chart repository.

note

New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.

helm fetch jetstack/cert-manager --version v1.7.1
3. Render the cert-manager template​

Render the cert-manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

helm template cert-manager ./cert-manager-v1.7.1.tgz --output-dir . \
    --namespace cert-manager \
    --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
    --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
    --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector \
    --set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-ctl
4. Download the cert-manager CRD​

Download the required CRD file for cert-manager:

curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml
5. Render the Rancher template​

Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

PlaceholderDescription
<VERSION>The version number of the output tarball.
<RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
<REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
<CERTMANAGER_VERSION>Cert-manager version running on k8s cluster.
helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set certmanager.version=<CERTMANAGER_VERSION> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

Optional: To install a specific Rancher version, set the rancherImageTag value, example: --set rancherImageTag=v2.5.8

Option B: Certificates From Files using Kubernetes Secrets​

1. Create secrets​

Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the hostname option in the command below, or the ingress controller will fail to provision the site for Rancher.

2. Render the Rancher template​

Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

PlaceholderDescription
<VERSION>The version number of the output tarball.
<RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
<REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
   helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set ingress.tls.source=secret \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

   helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
    --no-hooks \ # prevent files for Helm hooks from being generated
    --namespace cattle-system \
    --set hostname=<RANCHER.YOURDOMAIN.COM> \
    --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
    --set ingress.tls.source=secret \
    --set privateCA=true \
    --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    --set useBundledSystemChart=true # Use the packaged Rancher system charts

Optional: To install a specific Rancher version, set the rancherImageTag value, example: --set rancherImageTag=v2.3.6

Then refer to Adding TLS Secrets to publish the certificate files so Rancher and the ingress controller can use them.

4. Install Rancher​

Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.

Use kubectl to create namespaces and apply the rendered manifests.

If you choose to use self-signed certificates in B. Choose your SSL Configuration, install cert-manager.

For Self-Signed Certificate Installs, Install Cert-manager​

Click to expand

If you are using self-signed certificates, install cert-manager:

  1. Create the namespace for cert-manager.

    kubectl create namespace cert-manager

  2. Create the cert-manager CustomResourceDefinitions (CRDs).

    kubectl apply -f cert-manager/cert-manager-crd.yaml
    note

    If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above, or else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

  3. Launch cert-manager.

    kubectl apply -R -f ./cert-manager

Install Rancher with kubectl​

kubectl create namespace cattle-system
kubectl -n cattle-system apply -R -f ./rancher

The installation is complete.

caution

If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

Additional Resources​

These resources could be helpful when installing Rancher:

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html index 340b5c16706..04629e0ba6c 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html @@ -5,13 +5,13 @@ 2. Collect and Publish Images to your Private Registry | Rancher Manager - +
Version: v2.6

2. Collect and Publish Images to your Private Registry

This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.

By default, all images used to provision Kubernetes clusters or launch any tools in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.

Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.

The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any downstream Kubernetes clusters using Windows nodes, there are separate instructions to support the images needed.

Prerequisites:

You must have a private registry available to use.

If the registry has certs, follow this K3s documentation about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.

For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.

  1. Find the required assets for your Rancher version
  2. Collect the cert-manager image (unless you are bringing your own certificates or terminating TLS on a load balancer)
  3. Save the images to your workstation
  4. Populate the private registry

Prerequisites​

These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.

If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.

1. Find the required assets for your Rancher version​

  1. Go to our releases page, find the Rancher v2.x.x release that you want to install, and click Assets. Note: Don't use releases marked rc or Pre-release, as they are not stable for production environments.

  2. From the release's Assets section, download the following files, which are required to install Rancher in an air gap environment:

Release FileDescription
rancher-images.txtThis file contains a list of images needed to install Rancher, provision clusters and user Rancher tools.
rancher-save-images.shThis script pulls all the images in the rancher-images.txt from Docker Hub and saves all of the images as rancher-images.tar.gz.
rancher-load-images.shThis script loads images from the rancher-images.tar.gz file and pushes them to your private registry.

2. Collect the cert-manager image​

note

Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.

In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the cert-manager image to rancher-images.txt as well.

note

New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.

  1. Fetch the latest cert-manager Helm chart and parse the template for image details:

    note

    Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

    helm repo add jetstack https://charts.jetstack.io
    helm repo update
    helm fetch jetstack/cert-manager --version v1.7.1
    helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt

  2. Sort and unique the images list to remove any overlap between the sources:

    sort -u rancher-images.txt -o rancher-images.txt

3. Save the images to your workstation​

  1. Make rancher-save-images.sh an executable:

    chmod +x rancher-save-images.sh

  2. Run rancher-save-images.sh with the rancher-images.txt image list to create a tarball of all the required images:

    ./rancher-save-images.sh --image-list ./rancher-images.txt

    Result: Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named rancher-images.tar.gz. Check that the output is in the directory.

4. Populate the private registry​

Next, you will move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

Move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

The rancher-images.txt is expected to be on the workstation in the same directory that you are running the rancher-load-images.sh script. The rancher-images.tar.gz should also be in the same directory.

  1. Log into your private registry if required:

    docker login <REGISTRY.YOURDOMAIN.COM:PORT>

  2. Make rancher-load-images.sh an executable:

    chmod +x rancher-load-images.sh

  3. Use rancher-load-images.sh to extract, tag and push rancher-images.txt and rancher-images.tar.gz to your private registry:

    ./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>

Next step for Kubernetes Installs - Launch a Kubernetes Cluster​

Next step for Docker Installs - Install Rancher​

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html index d3970d8d373..ae07472f48b 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html @@ -5,13 +5,13 @@ 2. Install Kubernetes | Rancher Manager - +
Version: v2.6

2. Install Kubernetes

Once the infrastructure is ready, you can continue with setting up an RKE cluster to install Rancher in.

First, you have to install Docker and setup the HTTP proxy on all three Linux nodes. For this perform the following steps on all three nodes.

For convenience, export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell:

export proxy_host="10.0.0.5:8888"
export HTTP_PROXY=http://${proxy_host}
export HTTPS_PROXY=http://${proxy_host}
export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16

Next configure apt to use this proxy when installing packages. If you are not using Ubuntu, you have to adapt this step accordingly:

cat <<'EOF' | sudo tee /etc/apt/apt.conf.d/proxy.conf > /dev/null
Acquire::http::Proxy "http://${proxy_host}/";
Acquire::https::Proxy "http://${proxy_host}/";
EOF

Now you can install Docker:

curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh

Then ensure that your current user is able to access the Docker daemon without sudo:

sudo usermod -aG docker YOUR_USERNAME

And configure the Docker daemon to use the proxy to pull images:

sudo mkdir -p /etc/systemd/system/docker.service.d
cat <<'EOF' | sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null
[Service]
Environment="HTTP_PROXY=http://${proxy_host}"
Environment="HTTPS_PROXY=http://${proxy_host}"
Environment="NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"
EOF

To apply the configuration, restart the Docker daemon:

sudo systemctl daemon-reload
sudo systemctl restart docker

Air-gapped proxy​

New in v2.6.4

You can now provision node driver clusters from an air-gapped cluster configured to use a proxy for outbound connections.

In addition to setting the default rules for a proxy server, you will need to add additional rules, shown below, to provision node driver clusters from a proxied Rancher environment.

You will configure your filepath according to your setup, e.g., /etc/apt/apt.conf.d/proxy.conf:

acl SSL_ports port 22
acl SSL_ports port 2376

acl Safe_ports port 22      # ssh
acl Safe_ports port 2376    # docker port

Creating the RKE Cluster​

You need several command line tools on the host where you have SSH access to the Linux nodes to create and interact with the cluster:

sudo curl -fsSL -o /usr/local/bin/rke https://github.com/rancher/rke/releases/download/v1.1.4/rke_linux-amd64
sudo chmod +x /usr/local/bin/rke
curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x ./kubectl
sudo mv ./kubectl /usr/local/bin/kubectl
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod +x get_helm.sh
sudo ./get_helm.sh

Next, create a YAML file that describes the RKE cluster. Ensure that the IP addresses of the nodes and the SSH username are correct. For more information on the cluster YAML, have a look at the RKE documentation.

nodes:
  - address: 10.0.1.200
    user: ubuntu
    role: [controlplane,worker,etcd]
  - address: 10.0.1.201
    user: ubuntu
    role: [controlplane,worker,etcd]
  - address: 10.0.1.202
    user: ubuntu
    role: [controlplane,worker,etcd]

services:
  etcd:
    backup_config:
      interval_hours: 12
      retention: 6

After that, you can create the Kubernetes cluster by running:

rke up --config rancher-cluster.yaml

RKE creates a state file called rancher-cluster.rkestate, this is needed if you want to perform updates, modify your cluster configuration or restore it from a backup. It also creates a kube_config_cluster.yaml file, that you can use to connect to the remote Kubernetes cluster locally with tools like kubectl or Helm. Make sure to save all of these files in a secure location, for example by putting them into a version control system.

To have a look at your cluster run:

export KUBECONFIG=kube_config_cluster.yaml
kubectl cluster-info
kubectl get pods --all-namespaces

You can also verify that your external load balancer works, and the DNS entry is set up correctly. If you send a request to either, you should receive HTTP 404 response from the ingress controller:

$ curl 10.0.1.100
default backend - 404
$ curl rancher.example.com
default backend - 404

Save Your Files​

Important:

The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

Save a copy of the following files in a secure location:

  • rancher-cluster.yml: The RKE cluster configuration file.
  • kube_config_cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
  • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains the current state of the cluster including the RKE configuration and the certificates.
note

The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

Issues or errors?​

See the Troubleshooting page.

Next: Install Rancher​

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html index b4f4fc8462b..bb51bf408d2 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html @@ -5,13 +5,13 @@ 3. Install Rancher | Rancher Manager - +
Version: v2.6

3. Install Rancher

Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through cert-manager. In a real-world use-case you will likely use Let's Encrypt or provide your own certificate.

note

These installation instructions assume you are using Helm 3.

Install cert-manager​

Add the cert-manager helm repository:

helm repo add jetstack https://charts.jetstack.io

Create a namespace for cert-manager:

kubectl create namespace cert-manager

Install the CustomResourceDefinitions of cert-manager:

note

New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml

And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:

helm upgrade --install cert-manager jetstack/cert-manager \
  --namespace cert-manager --version v1.7.1 \
  --set http_proxy=http://${proxy_host} \
  --set https_proxy=http://${proxy_host} \
  --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local

Now you should wait until cert-manager is finished starting up:

kubectl rollout status deployment -n cert-manager cert-manager
kubectl rollout status deployment -n cert-manager cert-manager-webhook

Install Rancher​

Next you can install Rancher itself. First add the helm repository:

helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

Create a namespace:

kubectl create namespace cattle-system

And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata:

helm upgrade --install rancher rancher-latest/rancher \
   --namespace cattle-system \
   --set hostname=rancher.example.com \
   --set proxy=http://${proxy_host} \
   --set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local

After waiting for the deployment to finish:

kubectl rollout status deployment -n cattle-system rancher

You can now navigate to https://rancher.example.com and start using Rancher.

caution

If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

Additional Resources​

These resources could be helpful when installing Rancher:

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html index 17c106a795c..985c275a014 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html @@ -5,13 +5,13 @@ 1. Set up Infrastructure | Rancher Manager - +
Version: v2.6

1. Set up Infrastructure

In this section, you will provision the underlying infrastructure for your Rancher management server with internete access through a HTTP proxy.

To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

  • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
  • A load balancer to direct front-end traffic to the three nodes.
  • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

These nodes must be in the same region/data center. You may place these servers in separate availability zones.

Why three nodes?​

In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

1. Set up Linux Nodes​

These hosts will connect to the internet through an HTTP proxy.

Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

2. Set up the Load Balancer​

You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

  • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
  • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

For an example showing how to set up an NGINX load balancer, refer to this page.

For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

Important:

Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

3. Set up the DNS Record​

Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

Next: Set up a Kubernetes cluster​

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html index b2904025722..52afa7c8777 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html @@ -5,14 +5,14 @@ Certificate Troubleshooting | Rancher Manager - +
Version: v2.6

Certificate Troubleshooting

How Do I Know if My Certificates are in PEM Format?​

You can recognize the PEM format by the following traits:

  • The file begins with the following header:
    -----BEGIN CERTIFICATE-----
  • The header is followed by a long string of characters.
  • The file ends with a footer: -----END CERTIFICATE-----

PEM Certificate Example:

----BEGIN CERTIFICATE-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----

PEM Certificate Key Example:

-----BEGIN RSA PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END RSA PRIVATE KEY-----

If your key looks like the example below, see Converting a Certificate Key From PKCS8 to PKCS1.

-----BEGIN PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END PRIVATE KEY-----

Converting a Certificate Key From PKCS8 to PKCS1​

If you are using a PKCS8 certificate key file, Rancher will log the following line:

ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})

To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:

openssl rsa -in key.pem -out convertedkey.pem

You can now use convertedkey.pem as certificate key file for Rancher.

What is the Order of Certificates if I Want to Add My Intermediate(s)?​

The order of adding certificates is as follows:

-----BEGIN CERTIFICATE-----
%YOUR_CERTIFICATE%
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
%YOUR_INTERMEDIATE_CERTIFICATE%
-----END CERTIFICATE-----

How Do I Validate My Certificate Chain?​

You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. The ca.pem file must be the same as you added to the rancher/rancher container.

When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

Command:

openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
...
    Verify return code: 0 (ok)
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html index cadc5a50be2..3a09dc8cd23 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html @@ -5,13 +5,13 @@ Rolling Back Rancher Installed with Docker | Rancher Manager - +
Version: v2.6

Rolling Back Rancher Installed with Docker

If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before Docker Upgrade. Rolling back restores:

  • Your previous version of Rancher.
  • Your data backup created before upgrade.

Before You Start​

During rollback to a prior version of Rancher, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

In this command, <PRIOR_RANCHER_VERSION> is the version of Rancher you were running before your unsuccessful upgrade. v2.0.5 for example.

Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

Terminal docker ps Command, Displaying Where to Find <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME>![Placeholder Reference](/img/placeholder-ref-2.png)
PlaceholderExampleDescription
<PRIOR_RANCHER_VERSION>v2.0.5The rancher/rancher image you used before upgrade.
<RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
<RANCHER_VERSION>v2.0.5The version of Rancher that the backup is for.
<DATE>9-27-18The date that the data container or backup was created.

You can obtain <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

Rolling Back Rancher​

If you have issues upgrading Rancher, roll it back to its latest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade.

danger

Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur.

  1. Using a remote Terminal connection, log into the node running your Rancher Server.

  2. Pull the version of Rancher that you were running before upgrade. Replace the <PRIOR_RANCHER_VERSION> with that version.

    For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5.

    docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

  3. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

    docker stop <RANCHER_CONTAINER_NAME>

    You can obtain the name for your Rancher container by entering docker ps.

  4. Move the backup tarball that you created during completion of Docker Upgrade onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

    If you followed the naming convention we suggested in Docker Upgrade, it will have a name similar to (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

  5. Run the following command to replace the data in the rancher-data container with the data in the backup tarball, replacing the placeholder. Don't forget to close the quotes.

    docker run  --volumes-from rancher-data \
    -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \
    && tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

  6. Start a new Rancher Server container with the <PRIOR_RANCHER_VERSION> tag placeholder pointing to the data container.

    docker run -d --volumes-from rancher-data \
    --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    --privileged \
    rancher/rancher:<PRIOR_RANCHER_VERSION>

    Privileged access is required.

    danger

    Do not stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades.

  7. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored.

Result: Rancher is rolled back to its version and data state before upgrade.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html index b37f86a6b45..90300e991df 100644 --- a/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html +++ b/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html @@ -5,13 +5,13 @@ Upgrading Rancher Installed with Docker | Rancher Manager - +
Version: v2.6

Upgrading Rancher Installed with Docker

The following instructions will guide you through upgrading a Rancher server that was installed with Docker.

caution

Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. If you have already deployed a Docker install in production and need to upgrade to a new Rancher version, we recommend migrating to the Helm chart install before upgrading.

Prerequisites​

Placeholder Review​

During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>).

Here's an example of a command with a placeholder:

docker stop <RANCHER_CONTAINER_NAME>

In this command, <RANCHER_CONTAINER_NAME> is the name of your Rancher container.

Get Data for Upgrade Commands​

To obtain the data to replace the placeholders, run:

docker ps

Write down or copy this information before starting the upgrade.

Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

Placeholder Reference

PlaceholderExampleDescription
<RANCHER_CONTAINER_TAG>v2.1.3The rancher/rancher image you pulled for initial install.
<RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
<RANCHER_VERSION>v2.1.3The version of Rancher that you're creating a backup for.
<DATE>2018-12-19The date that the data container or backup was created.

You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

Upgrade​

During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data.

1. Create a copy of the data from your Rancher server container​

  1. Using a remote Terminal connection, log into the node running your Rancher server.

  2. Stop the container currently running Rancher server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

    docker stop <RANCHER_CONTAINER_NAME>
  3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
    docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>

2. Create a backup tarball​

  1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

    This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder.

    docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

    Step Result: When you enter this command, a series of commands should run.

  2. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    [rancher@ip-10-0-0-50 ~]$ ls
    rancher-data-backup-v2.1.3-20181219.tar.gz

  3. Move your backup tarball to a safe location external from your Rancher server.

3. Pull the New Docker Image​

Pull the image of the Rancher version that you want to upgrade to.

PlaceholderDescription
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
docker pull rancher/rancher:<RANCHER_VERSION_TAG>

4. Start the New Rancher Server Container​

Start a new Rancher server container using the data from the rancher-data container. Remember to pass in all the environment variables that you had used when you started the original container.

danger

Do not stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades.

If you used a proxy, see HTTP Proxy Configuration.

If you configured a custom CA root certificate to access your services, see Custom CA root certificate.

If you are recording all transactions with the Rancher API, see API Auditing

To see the command to use when starting the new Rancher server container, choose from the following options:

  • Docker Upgrade
  • Docker Upgrade for Air Gap Installs

Select which option you had installed Rancher server

Option A: Default Self-Signed Certificate​

Click to expand

If you have selected to use the Rancher generated self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container.

PlaceholderDescription
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

Privileged access is required.

Option B: Bring Your Own Certificate: Self-Signed​

Click to expand

If you have selected to bring your own self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with.

Reminder of the Cert Prerequisite:

The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.

PlaceholderDescription
<CERT_DIRECTORY>The path to the directory containing your certificate files.
<FULL_CHAIN.pem>The path to your full certificate chain.
<PRIVATE_KEY.pem>The path to the private key for your certificate.
<CA_CERTS.pem>The path to the certificate authority's certificate.
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG>

Privileged access is required.

Option C: Bring Your Own Certificate: Signed by Recognized CA​

Click to expand

If you have selected to use a certificate signed by a recognized CA, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include --no-cacerts as an argument to the container to disable the default CA certificate generated by Rancher.

Reminder of the Cert Prerequisite:

The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

PlaceholderDescription
<CERT_DIRECTORY>The path to the directory containing your certificate files.
<FULL_CHAIN.pem>The path to your full certificate chain.
<PRIVATE_KEY.pem>The path to the private key for your certificate.
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --no-cacerts

Privileged access is required.

Option D: Let's Encrypt Certificate​

Click to expand
caution

Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

If you have selected to use Let's Encrypt certificates, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher.

Reminder of the Cert Prerequisites:
  • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
  • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.
PlaceholderDescription
<RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
<YOUR.DNS.NAME>The domain address that you had originally started with
docker run -d --volumes-from rancher-data \
  --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:<RANCHER_VERSION_TAG> \
  --acme-domain <YOUR.DNS.NAME>

Privileged access is required.

Result: You have upgraded Rancher. Data from your upgraded server is now saved to the rancher-data container for use in future upgrades.

5. Verify the Upgrade​

Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window.

Having network issues in your user clusters following upgrade?

See Restoring Cluster Networking.

6. Clean up Your Old Rancher Server Container​

Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.

Rolling Back​

If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see Docker Rollback.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/add-tls-secrets.html b/getting-started/installation-and-upgrade/resources/add-tls-secrets.html index 44a9d71c6e3..ce8f2b1edeb 100644 --- a/getting-started/installation-and-upgrade/resources/add-tls-secrets.html +++ b/getting-started/installation-and-upgrade/resources/add-tls-secrets.html @@ -5,14 +5,14 @@ Adding TLS Secrets | Rancher Manager - +
Version: v2.6

Adding TLS Secrets

Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the tls-rancher-ingress secret in the cattle-system namespace with the certificate and key.

Combine the server certificate followed by any intermediate certificate(s) needed into a file named tls.crt. Copy your certificate key into a file named tls.key.

For example, acme.sh provides server certificate and CA chains in fullchain.cer file. This fullchain.cer should be renamed to tls.crt & certificate key file as tls.key.

Use kubectl with the tls secret type to create the secrets.

kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key
note

If you want to replace the certificate, you can delete the tls-rancher-ingress secret using kubectl -n cattle-system delete secret tls-rancher-ingress and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.

Using a Private CA Signed Certificate

If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.

Copy the CA certificate into a file named cacerts.pem and use kubectl to create the tls-ca secret in the cattle-system namespace.

kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem=./cacerts.pem
note

The configured tls-ca secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started.

Updating a Private CA Certificate

Follow the steps on this page to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/bootstrap-password.html b/getting-started/installation-and-upgrade/resources/bootstrap-password.html index edb88e8692d..3a5cbe397e8 100644 --- a/getting-started/installation-and-upgrade/resources/bootstrap-password.html +++ b/getting-started/installation-and-upgrade/resources/bootstrap-password.html @@ -5,13 +5,13 @@ Bootstrap Password | Rancher Manager - +
Version: v2.6

Bootstrap Password

When Rancher starts for the first time, a password is randomly generated for the first admin user. When the admin first logs in to Rancher, the UI shows commands that can be used to retrieve the bootstrap password. The admin needs to run those commands and log in with the bootstrap password. Then Rancher gives the admin an opportunity to reset the password.

The bootstrap password is randomly generated if it is not set during installation with a variable. For details on how to set the bootstrap password using a variable, see below.

Specifying the Bootstrap Password in Helm Installs​

For a Helm install, users can specify the bootstrap password variable by configuring it in the Helm chart values with .Values.bootstrapPassword.

The password will be stored in a Kubernetes secret. After Rancher is installed, the UI will show instructions for how to retrieve the password using kubectl:

kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ .data.bootstrapPassword|base64decode}}{{ "\n" }}'

Specifying the Bootstrap Password in Docker Installs​

For a Docker install, you can specify the bootstrap password by passing -e CATTLE_BOOTSTRAP_PASSWORD=password to the Docker install command.

The password will be stored in the Docker container logs. After Rancher is installed, the UI will show instructions for how to retrieve the password using the Docker container ID:

docker logs  container-id  2>&1 | grep "Bootstrap Password:"
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html b/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html index e09cb2561a2..31aaaade2e4 100644 --- a/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html +++ b/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html @@ -5,7 +5,7 @@ Choosing a Rancher Version | Rancher Manager - + @@ -14,7 +14,7 @@     helm search repo --versions

If you have several repos you can specify the repo name, ie. helm search repo rancher-stable/rancher --versions
For more information, see https://helm.sh/docs/helm/helm_search_repo/

To fetch a specific version of your chosen repo, define the --version parameter like in the following example:
    helm fetch rancher-stable/rancher --version=2.4.8

Switching to a Different Helm Chart Repository​

After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps.

note

Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported.

  • Latest: Recommended for trying out the newest features
    helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
  • Stable: Recommended for production environments
    helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
  • Alpha: Experimental preview of upcoming releases.
    helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
    Note: Upgrades are not supported to, from, or between Alphas.

  1. List the current Helm chart repositories.

    helm repo list

    NAME                  URL
    stable                https://charts.helm.sh/stable
    rancher-<CHART_REPO>        https://releases.rancher.com/server-charts/<CHART_REPO>

  2. Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be rancher-stable or rancher-latest depending on what you had initially added.

    helm repo remove rancher-<CHART_REPO>

  3. Add the Helm chart repository that you want to start installing Rancher from.

    helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>

  4. Continue to follow the steps to upgrade Rancher from the new Helm chart repository.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html b/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html index d7fbe932a21..01c918a41d2 100644 --- a/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html +++ b/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html @@ -5,13 +5,13 @@ About Custom CA Root Certificates | Rancher Manager - +
Version: v2.6

About Custom CA Root Certificates

If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).

Services that Rancher needs to access are sometimes configured with a certificate from a custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: x509: certificate signed by unknown authority.

To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable SSL_CERT_DIR to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (-v host-source-directory:container-destination-directory) when starting the Rancher container.

Examples of services that Rancher can access:

  • Catalogs
  • Authentication providers
  • Accessing hosting/cloud API when using Node Drivers

Installing with the custom CA Certificate​

For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs:

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/helm-version-requirements.html b/getting-started/installation-and-upgrade/resources/helm-version-requirements.html index 0129dee31b2..4a4687eeb83 100644 --- a/getting-started/installation-and-upgrade/resources/helm-version-requirements.html +++ b/getting-started/installation-and-upgrade/resources/helm-version-requirements.html @@ -5,13 +5,13 @@ Helm Version Requirements | Rancher Manager - +
Version: v2.6

Helm Version Requirements

This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.

The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 Migration Docs. This section provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

  • Helm v3.2.x or higher is required to install or upgrade Rancher v2.5.
  • Helm v2.16.0 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the release notes for the version of RKE that you are using.
  • Helm v2.15.0 should not be used, because of an issue with converting/comparing numbers.
  • Helm v2.12.0 should not be used, because of an issue with cert-manager.
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/local-system-charts.html b/getting-started/installation-and-upgrade/resources/local-system-charts.html index cf0c9d4b443..eb151554324 100644 --- a/getting-started/installation-and-upgrade/resources/local-system-charts.html +++ b/getting-started/installation-and-upgrade/resources/local-system-charts.html @@ -5,13 +5,13 @@ Setting up Local System Charts for Air Gapped Installations | Rancher Manager - +
Version: v2.6

Setting up Local System Charts for Air Gapped Installations

The System Charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS.

In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag.

Using Local System Charts

A local copy of system-charts has been packaged into the rancher/rancher container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, CATTLE_SYSTEM_CATALOG=bundled, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub.

Example commands for a Rancher installation with a bundled system-charts are included in the air gap installation instructions for Docker and Helm installs.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html b/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html index 7f98cb69537..03b594dace9 100644 --- a/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html +++ b/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html @@ -5,14 +5,14 @@ Updating the Rancher Certificate | Rancher Manager - +
Version: v2.6

Updating a Private CA Certificate

Follow these steps to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

A summary of the steps is as follows:

  1. Create or update the tls-rancher-ingress Kubernetes secret resource with the new certificate and private key.
  2. Create or update the tls-ca Kubernetes secret resource with the root CA certificate (only required when using a private CA).
  3. Update the Rancher installation using the Helm CLI.
  4. Reconfigure the Rancher agents to trust the new CA certificate.
  5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher.

The details of these instructions are below.

1. Create/update the certificate secret resource​

First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

Alternatively, to update an existing certificate secret:

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key \
  --dry-run --save-config -o yaml | kubectl apply -f -

2. Create/update the CA certificate secret resource​

If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named cacerts.pem and create or update the tls-ca secret in the cattle-system namespace. If the certificate was signed by an intermediate CA, then the cacerts.pem must contain both the intermediate and root CA certificates (in this order).

To create the initial secret:

$ kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem

To update an existing tls-ca secret:

$ kubectl -n cattle-system create secret generic tls-ca \
  --from-file=cacerts.pem \
  --dry-run --save-config -o yaml | kubectl apply -f -

3. Reconfigure the Rancher deployment​

note

Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4.

This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

$ helm get values rancher -n cattle-system

Also get the version string of the currently deployed Rancher chart:

$ helm ls -A

Upgrade the Helm application instance using the original configuration values and making sure to specify ingress.tls.source=secret as well as the current chart version to prevent an application upgrade.

If the certificate was signed by a private CA, add the set privateCA=true argument as well. Also make sure to read the documentation describing the initial installation using custom certificates.

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version <DEPLOYED_CHART_VERSION> \
  --set hostname=rancher.my.org \
  --set ingress.tls.source=secret \
  --set ...

When the upgrade is completed, navigate to https://<Rancher_SERVER>/v3/settings/cacerts to verify that the value matches the CA certificate written in the tls-ca secret earlier.

4. Reconfigure Rancher agents to trust the private CA​

This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true:

  • Rancher was initially configured to use the Rancher self-signed certificate (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt)
  • The root CA certificate for the new custom certificate has changed

Why is this step required?​

When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the CATTLE_CA_CHECKSUM environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable CATTLE_CA_CHECKSUM must be updated accordingly.

Which method should I choose?​

Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3).

If the clusters have lost connection to Rancher but you have Authorized Cluster Endpoints enabled, then go with method 2.

Method 3 can be used as a fallback if method 1 and 2 are unfeasible.

Method 1: Kubectl command​

For each cluster under Rancher management (except the local Rancher management cluster) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S).

kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge

This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate.

Method 2: Manually update checksum​

Manually patch the agent Kubernetes resources by updating the CATTLE_CA_CHECKSUM environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:

$ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
$ sha256sum cacert.tmp | awk '{print $1}'

Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments.

$ kubectl edit -n cattle-system ds/cattle-node-agent
$ kubectl edit -n cattle-system deployment/cattle-cluster-agent

Method 3: Recreate Rancher agents​

With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster.

First, generate the agent definitions as described here: https://gist.github.com/superseb/076f20146e012f1d4e289f5bd1bd4971

Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions: https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b

5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher​

Select 'Force Update' for the clusters within the Continuous Delivery view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

Why is this step required?​

Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.

Updating from a Private CA Certificate to a Common Certificate

note

It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below.

1. Create/update the certificate secret resource​

First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key

Alternatively, to update an existing certificate secret:

$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
  --cert=tls.crt \
  --key=tls.key \
  --dry-run --save-config -o yaml | kubectl apply -f -

2. Delete the CA certificate secret resource​

You will delete the tls-ca secret in the cattle-system namespace as it is no longer needed. You may also optionally save a copy of the tls-ca secret if desired.

To save the existing secret:

kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml

To delete the existing tls-ca secret:

kubectl -n cattle-system delete secret tls-ca

3. Reconfigure the Rancher deployment​

Important:

Before proceeding, generate an API token in the Rancher UI (User > API & Keys).

This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

$ helm get values rancher -n cattle-system

Also get the version string of the currently deployed Rancher chart:

$ helm ls -A

Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.

Also make sure to read the documentation describing the initial installation using custom certificates.

helm upgrade rancher rancher-stable/rancher \
  --namespace cattle-system \
  --version <DEPLOYED_CHART_VERSION> \
  --set hostname=rancher.my.org \
  --set ...

On upgrade, you can either

  • remove --set ingress.tls.source=secret \ from the Helm upgrade command, as shown above, or

  • remove the privateCA parameter or set it to false because the CA is valid:

set privateCA=false

4. Reconfigure Rancher agents for the non-private/common certificate​

CATTLE_CA_CHECKSUM environment variable on the downstream cluster agents should be removed or set to "" (an empty string).

5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher​

Select 'Force Update' for the clusters within the Continuous Delivery view of the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

Why is this step required?​

Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html b/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html index b6f9816d7a4..490eb641e00 100644 --- a/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html +++ b/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html @@ -5,13 +5,13 @@ Upgrading Cert-Manager | Rancher Manager - +
Version: v2.6

Upgrading Cert-Manager

Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:

  1. Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.
  2. Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field. This change has no exact deadline.
  3. Cert-manager is deprecating v1alpha1 API and replacing its API group

To address these changes, this guide will do two things:

  1. Document the procedure for upgrading cert-manager
  2. Explain the cert-manager API changes and link to cert-manager's official documentation for migrating your data
Important:

If you are upgrading cert-manager to the latest version from a version older than 1.5, follow the steps in Option C below to do so. Note that you do not need to reinstall Rancher to perform this upgrade.

Upgrade Cert-Manager

The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running kubectl get pods --all-namespaces and checking which namespace the cert-manager-* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues.

In order to upgrade cert-manager, follow these instructions:

Option A: Upgrade cert-manager with Internet Access​

Click to expand

  1. Back up existing resources as a precaution

    kubectl get -o yaml --all-namespaces \
    issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
    Important:

    If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from certmanager.k8s.io/v1alpha1 to cert-manager.io/v1alpha2. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on additional annotation changes.

  2. Uninstall existing deployment

    helm uninstall cert-manager

    Delete the CustomResourceDefinition using the link to the version vX.Y.Z you installed

    kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml

  3. Install the CustomResourceDefinition resources separately

    kubectl apply --validate=false -f https://github.com/cert-manager/cert-manager/releases/download/vX.Y.Z/cert-manager.crds.yaml

    note

    If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

  4. Create the namespace for cert-manager if needed

    kubectl create namespace cert-manager

  5. Add the Jetstack Helm repository

    helm repo add jetstack https://charts.jetstack.io

  6. Update your local Helm chart repository cache

    helm repo update

  7. Install the new version of cert-manager

    helm install \
      cert-manager jetstack/cert-manager \
      --namespace cert-manager \
      --version v0.12.0

  8. Restore back up resources

    kubectl apply -f cert-manager-backup.yaml

Option B: Upgrade cert-manager in an Air-Gapped Environment​

Click to expand

Prerequisites​

Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.

  1. Follow the guide to Prepare your Private Registry with the images needed for the upgrade.

  2. From a system connected to the internet, add the cert-manager repo to Helm

    helm repo add jetstack https://charts.jetstack.io
    helm repo update

  3. Fetch the latest cert-manager chart available from the Helm chart repository.

    helm fetch jetstack/cert-manager --version v0.12.0

  4. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

    The Helm 3 command is as follows:

    helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \
    --namespace cert-manager \
    --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
    --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
    --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

    The Helm 2 command is as follows:

    helm template ./cert-manager-v0.12.0.tgz --output-dir . \
    --name cert-manager --namespace cert-manager \
    --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
    --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
    --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

  5. Download the required CRD file for cert-manager (old and new)

    curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
    curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/cert-manager/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml

Install cert-manager​

  1. Back up existing resources as a precaution

    kubectl get -o yaml --all-namespaces \
    issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml
    Important:

    If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from certmanager.k8s.io/v1alpha1 to cert-manager.io/v1alpha2. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on additional annotation changes.

  2. Delete the existing cert-manager installation

    kubectl -n cert-manager \
    delete deployment,sa,clusterrole,clusterrolebinding \
    -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

    Delete the CustomResourceDefinition using the link to the version vX.Y you installed

    kubectl delete -f cert-manager/cert-manager-crd-old.yaml

  3. Install the CustomResourceDefinition resources separately

    kubectl apply -f cert-manager/cert-manager-crd.yaml
    Important:

    If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

  4. Create the namespace for cert-manager

    kubectl create namespace cert-manager

  5. Install cert-manager

    kubectl -n cert-manager apply -R -f ./cert-manager

  6. Restore back up resources

    kubectl apply -f cert-manager-backup.yaml

Option C: Upgrade cert-manager from Versions 1.5 and Below​

Click to expand

Previously, in order to upgrade cert-manager from an older version, an uninstall and reinstall of Rancher was recommended. Using the method below, you may upgrade cert-manager without those additional steps in order to better preserve your production environment:

  1. Install cmctl, the cert-manager CLI tool, using the installation guide.

  2. Ensure that any cert-manager custom resources that may have been stored in etcd at a deprecated API version get migrated to v1:

    cmctl upgrade migrate-api-version

    Refer to the API version migration docs for more information. Please also see the docs to upgrade from 1.5 to 1.6 and the docs to upgrade from 1.6. to 1.7 if needed.

  3. Upgrade cert-manager to v1.7.1 with a normal helm upgrade. You may go directly from version 1.5 to 1.7 if desired.

  4. Follow the Helm tutorial to update the API version of a release manifest. The chart release name is release_name=rancher and the release namespace is release_namespace=cattle-system.

  5. In the decoded file, search for cert-manager.io/v1beta1 and replace it with cert-manager.io/v1.

  6. Upgrade Rancher normally with helm upgrade.

Verify the Deployment​

Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:

kubectl get pods --namespace cert-manager

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

Cert-Manager API change and data migration​

New in v2.6.4

Rancher now supports cert-manager versions 1.6.2 and 1.7.1. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022. To read more, see the cert-manager docs. For instructions on upgrading cert-manager from version 1.5 to 1.6, see the upstream cert-manager documentation here. For instructions on upgrading cert-manager from version 1.6 to 1.7, see the upstream cert-manager documentation here.

Cert-manager has deprecated the use of the certificate.spec.acme.solvers field and will drop support for it completely in an upcoming release.

Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.

Details about the change and migration instructions can be found in the cert-manager v0.7 to v0.8 upgrade instructions.

The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.

We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the upgrading to v0.8 guide.

Details about the change and migration instructions can be found in the cert-manager v0.10 to v0.11 upgrade instructions.

More info about cert-manager upgrade information.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html b/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html index cbc07f2c61b..2a8467a7b8f 100644 --- a/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html +++ b/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html @@ -5,13 +5,13 @@ Upgrading and Rolling Back Kubernetes | Rancher Manager - +
Version: v2.6

Upgrading and Rolling Back Kubernetes

Following an upgrade to the latest version of Rancher, downstream Kubernetes clusters can be upgraded to use the latest supported version of Kubernetes.

Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the RKE documentation.

Tested Kubernetes Versions​

Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the support maintenance terms.

How Upgrades Work​

RKE v1.1.0 changed the way that clusters are upgraded.

In this section of the RKE documentation, you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster.

When upgrading the Kubernetes version of a cluster, we recommend that you:

  1. Take a snapshot.
  2. Initiate a Kubernetes upgrade.
  3. If the upgrade fails, revert the cluster to the pre-upgrade Kubernetes version. This is achieved by selecting the Restore etcd and Kubernetes version option. This will return your cluster to the pre-upgrade kubernetes version before restoring the etcd snapshot.

The restore operation will work on a cluster that is not in a healthy or active state.

Upgrading the Kubernetes Version​

Prerequisites:
  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster you want to upgrade and click ⋮ > Edit Config.
  3. From the Kubernetes Version drop-down, choose the version of Kubernetes that you want to use for the cluster.
  4. Click Save.

Result: Kubernetes begins upgrading for the cluster.

Rolling Back​

A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections:

Configuring the Upgrade Strategy​

As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain conditions and requirements are met.

The upgrade strategy can be configured in the Rancher UI, or by editing the cluster.yml. More advanced options are available by editing the cluster.yml.

Configuring the Maximum Unavailable Worker Nodes in the Rancher UI​

From the Rancher UI, the maximum number of unavailable worker nodes can be configured. During a cluster upgrade, worker nodes will be upgraded in batches of this size.

By default, the maximum number of unavailable worker is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node.

To change the default number or percentage of worker nodes,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster you want to upgrade and click ⋮ > Edit Config.
  3. In the Upgrade Strategy tab, enter the Worker Concurrency as a fixed number or percentage. To get this number, you can take the number of nodes in your cluster and subtract the max unavailable nodes.
  4. Click Save.

Result: The cluster is updated to use the new upgrade strategy.

Enabling Draining Nodes During Upgrades from the Rancher UI​

By default, RKE cordons each node before upgrading it. Draining is disabled during upgrades by default. If draining is enabled in the cluster configuration, RKE will both cordon and drain the node before it is upgraded.

To enable draining each node during a cluster upgrade,

  1. In the upper left corner, click ☰ > Cluster Management.
  2. On the Clusters page, go to the cluster you want to enable node draining and click ⋮ > Edit Config.
  3. Click ⋮ > Edit.
  4. In the Upgrade Strategy tab, go to the Drain nodes field and click Yes. Node draining is configured separately for control plane and worker nodes.
  5. Configure the options for how pods are deleted. For more information about each option, refer to this section.
  6. Optionally, configure a grace period. The grace period is the timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. Pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If this value is negative, the default value specified in the pod will be used.
  7. Optionally, configure a timeout, which is the amount of time the drain should continue to wait before giving up.
  8. Click Save.

Result: The cluster is updated to use the new upgrade strategy.

note

As of Rancher v2.4.0, there is a known issue in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.

Maintaining Availability for Applications During Upgrades​

Available as of RKE v1.1.0

In this section of the RKE documentation, you'll learn the requirements to prevent downtime for your applications when upgrading the cluster.

Configuring the Upgrade Strategy in the cluster.yml​

More advanced upgrade strategy configuration options are available by editing the cluster.yml.

For details, refer to Configuring the Upgrade Strategy in the RKE documentation. The section also includes an example cluster.yml for configuring the upgrade strategy.

Troubleshooting​

If a node doesn't come up after an upgrade, the rke up command errors out.

No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum.

If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue.

A failed node could be in many different states:

  • Powered off
  • Unavailable
  • User drains a node while upgrade is in process, so there are no kubelets on the node
  • The upgrade itself failed

If the max unavailable number of nodes is reached during an upgrade, Rancher user clusters will be stuck in updating state and not move forward with upgrading any other control plane nodes. It will continue to evaluate the set of unavailable nodes in case one of the nodes becomes available. If the node cannot be fixed, you must remove the node in order to continue the upgrade.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html b/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html index 10bc5563878..0a400dce999 100644 --- a/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html +++ b/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html @@ -5,13 +5,13 @@ Upgrading Kubernetes without Upgrading Rancher | Rancher Manager - +
Version: v2.6

Upgrading Kubernetes without Upgrading Rancher

The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.

note

The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.

Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision RKE clusters. Rancher syncs the data periodically and creates custom resource definitions (CRDs) for system images, service options and addon templates. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the Rancher Kubernetes Engine (RKE) uses for deploying various Kubernetes versions.

This table below describes the CRDs that are affected by the periodic data sync.

note

Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.

ResourceDescriptionRancher API URL
System ImagesList of system images used to deploy Kubernetes through RKE.<RANCHER_SERVER_URL>/v3/rkek8ssystemimages
Service OptionsDefault options passed to Kubernetes components like kube-api, scheduler, kubelet, kube-proxy, and kube-controller-manager<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions
Addon TemplatesYAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, metrics-server, nginx-ingress<RANCHER_SERVER_URL>/v3/rkeaddons

Administrators might configure the RKE metadata settings to do the following:

  • Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher
  • Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
  • Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher

Refresh Kubernetes Metadata​

The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the Manage Cluster Drivers global role.

To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available:

  1. In the upper left corner, click ☰ > Cluster Management.
  2. In the left navigation menu, click Drivers.
  3. Click Refresh Kubernetes Metadata.

You can configure Rancher to only refresh metadata when desired by setting refresh-interval-minutes to 0 (see below) and using this button to perform the metadata refresh manually when desired.

Configuring the Metadata Synchronization​

caution

Only administrators can change these settings.

The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint v3/settings/rke-metadata-config.

The way that the metadata is configured depends on the Rancher version.

To edit the metadata config in Rancher,

  1. In the upper left corner, click ☰ > Global Settings.
  2. Go to the rke-metadata-config section. Click ⋮ > Edit Setting.
  3. You can optionally fill in the following parameters:
  • refresh-interval-minutes: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set refresh-interval-minutes to 0.
  • url: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json.
  1. Click Save.

If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from Rancher's metadata Git repository.

However, if you have an air gap setup, you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.

Air Gap Setups​

Rancher relies on a periodic refresh of the rke-metadata-config to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the service terms section.

If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.

To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the rke-metadata-config settings to point to the mirror. For details, refer to Configuring the Metadata Synchronization.

After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.

  1. To download the system images for the private registry, click the Rancher server version at the bottom left corner of the Rancher UI.
  2. Download the OS specific image lists for Linux or Windows.
  3. Download rancher-images.txt.
  4. Prepare the private registry using the same steps during the air gap install, but instead of using the rancher-images.txt from the releases page, use the one obtained from the previous steps.

Result: The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/introduction/overview.html b/getting-started/introduction/overview.html index 540717e80c0..a09c843c98d 100644 --- a/getting-started/introduction/overview.html +++ b/getting-started/introduction/overview.html @@ -5,13 +5,13 @@ Overview | Rancher Manager - +
Version: v2.6

Overview

Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams.

Run Kubernetes Everywhere

Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer.

Meet IT Requirements

Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can:

  • Use your Active Directory credentials to access Kubernetes clusters hosted by cloud vendors, such as GKE.
  • Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds.
  • View the health and capacity of your Kubernetes clusters from a single-pane-of-glass.

Empower DevOps Teams

Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers.

The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds.

Platform

Features of the Rancher API Server

The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:

Authorization and Role-Based Access Control​

  • User management: The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub, in addition to local users.
  • Authorization: The Rancher API server manages access control and security policies.

Working with Kubernetes​

  • Provisioning Kubernetes clusters: The Rancher API server can provision Kubernetes on existing nodes, or perform Kubernetes upgrades.
  • Catalog management: Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications.
  • Managing projects: A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for project administration and for managing applications within projects.
  • Fleet Continuous Delivery: Within Rancher, you can leverage Fleet Continuous Delivery to deploy applications from git repositories, without any manual operation, to targeted downstream Kubernetes clusters.
  • Istio: Our integration with Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

Working with Cloud Infrastructure​

  • Tracking nodes: The Rancher API server tracks identities of all the nodes in all clusters.
  • Setting up infrastructure: When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud.

Cluster Visibility​

  • Logging: Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters.
  • Monitoring: Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.
  • Alerting: To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned.

Editing Downstream Clusters with Rancher

The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters provisioned by RKE have Cluster Options available for editing.

After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among other options.

The following table summarizes the options and settings available for each cluster type:

ActionRancher Launched Kubernetes ClustersEKS, GKE and AKS Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
Managing Cluster Members✓✓✓✓
Editing and Upgrading Clusters✓✓✓✓2
Managing Nodes✓✓✓✓3
Managing Persistent Volumes and Storage Classes✓✓✓✓
Managing Projects, Namespaces and Workloads✓✓✓✓
Using App Catalogs✓✓✓✓
Configuring Tools (Alerts, Notifiers, Monitoring, Logging, Istio)✓✓✓✓
Running Security Scans✓✓✓✓
Use existing configuration to create additional clusters✓✓✓
Ability to rotate certificates✓✓
Ability to backup and restore Rancher-launched clusters✓✓✓4
Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
Configuring Pod Security Policies✓✓

  1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

  2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

  3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

  4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/introduction/what-are-divio-docs.html b/getting-started/introduction/what-are-divio-docs.html index f2a9974c05f..5a73707b6fc 100644 --- a/getting-started/introduction/what-are-divio-docs.html +++ b/getting-started/introduction/what-are-divio-docs.html @@ -5,13 +5,13 @@ What Are Divio Docs? | Rancher Manager - +
Version: v2.6

What Are Divio Docs?

The Divio documentation system is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.

In our docs, we have used this guideline to craft a unique set of docs which include getting started, how-to guides (including new and advanced user guides), reference guides, explanations, an FAQ section, troubleshooting tips, and the ability to contribute to Rancher.

Getting Started​

To get up and running with Rancher quickly, we have included a Getting Started section.

The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

Please see the introduction, quick start guides, and the installation and upgrade sections for more.

How-to Guides​

How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

New User Guides​

New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

A good example of a new user guide can be found here.

Advanced User Guides​

Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they have encountered while working.

It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

A good example of an advanced user guide can be found here.

Reference Guides​

Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

Explanations​

Explanation docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.

For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature Integrations in Rancher to discuss our integrated products.

Integrations in Rancher​

Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under Explanations.

Examples of some of these integrations are Harvester and NeuVector.

Other Docs Categories​

FAQ​

Our FAQ section is designed to answer the questions our users have been most often asking about Rancher v2.x. The nature of these questions may be technical or non-technical.

We work to continually add to and enhance this section; check back frequently for updates.

Troubleshooting​

The troubleshooting section is designed to help both new and existing Rancher users to troubleshoot known issues that they may encounter when using Rancher.

We work to continually add to and enhance this section; check back frequently for updates.

Contribute to Rancher​

The Rancher Manager documentation is always a work-in-progress; the docs work best when being constantly examined, updated, and improved upon. To do this more effectively, we call upon the community to assist us.

This contributing to Rancher section will instruct users on the repositories used for Rancher, how to build the repositories, and what information is needed when filing an issue or creating a pull request.

We review all contributions frequently and will provide feedback to contributors promptly.

Overlapping of Categories​

You may have noticed that within the confines of each category - new user guides, advanced user guides, references - there is some overlap. This is true because the flow of information is fluid, and so often docs will include data that could logically fall under more than one category. Although there is the tendency for our docs to overlap somewhat, if we keep in mind the primary functions of each category and work to make those distinct, then the documentation will be much clearer and useful for users.

New Structure Goals​

Our previous Rancher documentation focused on individual features and topics; the new Divio paradigm prioritizes function and cohesion.

Because the previous docs structure was not based on the Divio paradigm, not every doc as it is written currently will fall neatly into a user guide or a reference, for example. Some docs may include elements of several kind of documentation functions.

As such, we have worked to move our existing documentation into the new paradigm based on each doc's function. Moving forward, we will be creating, rewriting, and reshaping our docs as needed to more closely align with the Divio structure, purpose, and its design concepts.

Ultimately, the finished product will much more cohesively and effectively assist our users by emphasizing functionality over individual topic or feature-based docs.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.html b/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.html index de23ae97734..7d8cc8181d1 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/aws-marketplace.html @@ -5,13 +5,13 @@ Rancher AWS Marketplace Quick Start | Rancher Manager - +
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/aws.html b/getting-started/quick-start-guides/deploy-rancher-manager/aws.html index 04b6296a62a..61e0d10b8e3 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/aws.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/aws.html @@ -5,14 +5,14 @@ Rancher AWS Quick Start Guide | Rancher Manager - +
Version: v2.6

Rancher AWS Quick Start Guide

The following steps will quickly deploy a Rancher server on AWS in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to Amazon AWS will incur charges.

  • Amazon AWS Account: An Amazon AWS Account is required to create resources for deploying Rancher and Kubernetes.
  • Amazon AWS Access Key: Use this link to follow a tutorial to create an Amazon AWS Access Key if you don't have one yet.
  • IAM Policy created: Defines the permissions an account attached with this policy has.
  • Install Terraform: Used to provision the server and cluster in Amazon AWS.

Example IAM Policy​

The AWS module just creates an EC2 KeyPair, an EC2 SecurityGroup and an EC2 instance. A simple policy would be:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*"
        }
    ]
}

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the AWS folder containing the terraform files by executing cd quickstart/rancher/aws.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • aws_access_key - Amazon AWS Access Key
    • aws_secret_key - Amazon AWS Secret Key
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the AWS Quickstart Readme for more information. Suggestions include:

    • aws_region - Amazon AWS region, choose the closest instead of the default (us-east-1)
    • prefix - Prefix for all created resources
    • instance_type - EC2 instance size used, minimum is t3a.medium but t3a.large or t3a.xlarge could be used if within budget
    • add_windows_node - If true, an additional Windows worker node is added to the workload cluster

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/aws.

Result​

Two Kubernetes clusters are deployed into your AWS account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/aws folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/azure.html b/getting-started/quick-start-guides/deploy-rancher-manager/azure.html index 1a82f94cb0f..2927b0d0e1b 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/azure.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/azure.html @@ -5,14 +5,14 @@ Rancher Azure Quick Start Guide | Rancher Manager - +
Version: v2.6

Rancher Azure Quick Start Guide

The following steps will quickly deploy a Rancher server on Azure in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to Microsoft Azure will incur charges.

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the Azure folder containing the terraform files by executing cd quickstart/rancher/azure.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • azure_subscription_id - Microsoft Azure Subscription ID
    • azure_client_id - Microsoft Azure Client ID
    • azure_client_secret - Microsoft Azure Client Secret
    • azure_tenant_id - Microsoft Azure Tenant ID
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the Azure Quickstart Readme for more information. Suggestions include:

    • azure_location - Microsoft Azure region, choose the closest instead of the default (East US)
    • prefix - Prefix for all created resources
    • instance_type - Compute instance size used, minimum is Standard_DS2_v2 but Standard_DS2_v3 or Standard_DS3_v2 could be used if within budget
    • add_windows_node - If true, an additional Windows worker node is added to the workload cluster
    • windows_admin_password - The admin password of the windows worker node

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/azure.

Result​

Two Kubernetes clusters are deployed into your Azure account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/azure folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html b/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html index 2ce844d1094..b6ad5c0581b 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html @@ -5,14 +5,14 @@ Rancher DigitalOcean Quick Start Guide | Rancher Manager - +
Version: v2.6

Rancher DigitalOcean Quick Start Guide

The following steps will quickly deploy a Rancher server on DigitalOcean in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to DigitalOcean will incur charges.

  • DigitalOcean Account: You will require an account on DigitalOcean as this is where the server and cluster will run.
  • DigitalOcean Access Key: Use this link to create a DigitalOcean Access Key if you don't have one.
  • Terraform: Used to provision the server and cluster to DigitalOcean.

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the DigitalOcean folder containing the terraform files by executing cd quickstart/rancher/do.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • do_token - DigitalOcean access key
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the DO Quickstart Readme for more information. Suggestions include:

    • do_region - DigitalOcean region, choose the closest instead of the default (nyc1)
    • prefix - Prefix for all created resources
    • droplet_size - Droplet size used, minimum is s-2vcpu-4gb but s-4vcpu-8gb could be used if within budget

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/do.

Result​

Two Kubernetes clusters are deployed into your DigitalOcean account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/do folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.html b/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.html index 604ab6caedb..cdef19f86e8 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/equinix-metal.html @@ -5,13 +5,13 @@ Rancher Equinix Metal Quick Start | Rancher Manager - +
Version: v2.6

Rancher Equinix Metal Quick Start

This tutorial walks you through the following:​

  • Provisioning an Equinix Metal Server
  • Installation of Rancher 2.x
  • Creation of your first cluster
  • Deployment of an application, Nginx
caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. The Docker install is not recommended for production environments. For comprehensive setup instructions, see Installation.

Quick Start Outline​

This Quick Start Guide is divided into different tasks for easier consumption.


Prerequisites​

1. Provision a Equinix Metal Host​

Begin deoploying an Equinix Metal Host. Equinix Metal Servers can be provisioned by either the Equinix Metal console, api, or cli. You can find instructions on how to deploy with each deployment type on the Equinix Metal deployment documentation. Yopu can find additional documentation on Equinix Metal server types and prices below.

Notes:
  • When provisioning a new Equinix Metal Server via the CLI or API you will need to be able to provide the following information: project-id, plan, metro, and the operating-system
  • When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration.
  • For a full list of port requirements, refer to Docker Installation.
  • Provision the host according to our Requirements.

2. Install Rancher​

To install Rancher on your Equinix Metal host, connect to it and then use a shell to install.

  1. Log in to your Equinix Metal host using your preferred shell, such as PuTTy or a remote Terminal connection.

  2. From your shell, enter the following command:

    sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher

Result: Rancher is installed.

3. Log In​

Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations.

  1. Open a web browser and enter the IP address of your host: https://<SERVER_IP>.

    Replace <SERVER_IP> with your host IP address.

  2. When prompted, create a password for the default admin account there cowpoke!

  3. Set the Rancher Server URL. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.

    If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster.


4. Create the Cluster​

Welcome to Rancher! You are now able to create your first Kubernetes cluster.

In this task, you can use the versatile Custom option. This option lets you add any Linux host (cloud-hosted VM, on-prem VM, or bare-metal) to be used in a cluster.

  1. Click ☰ > Cluster Management.

  2. From the Clusters page, click Create.

  3. Choose Custom.

  4. Enter a Cluster Name.

  5. Skip Member Roles and Cluster Options. We'll tell you about them later.

  6. Click Next.

  7. From Node Role, select all the roles: etcd, Control, and Worker.

  8. Optional: Rancher auto-detects the IP addresses used for Rancher communication and cluster communication. You can override these using Public Address and Internal Address in the Node Address section.

  9. Skip the Labels stuff. It's not important for now.

  10. Copy the command displayed on screen to your clipboard.

  11. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

  12. When you finish running the command on your Linux host, click Done.

Result:

Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

You can access your cluster after its state is updated to Active.

Active clusters are assigned two Projects:

  • Default, containing the default namespace
  • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

Finished​

Congratulations! You have created your first cluster.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html b/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html index 0739574d19c..17beb261233 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html @@ -5,7 +5,7 @@ Rancher GCP Quick Start Guide | Rancher Manager - + @@ -13,7 +13,7 @@
Version: v2.6

Rancher GCP Quick Start Guide

The following steps will quickly deploy a Rancher server on GCP in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to Google GCP will incur charges.

  • Google GCP Account: A Google GCP Account is required to create resources for deploying Rancher and Kubernetes.
  • Google GCP Project: Use this link to follow a tutorial to create a GCP Project if you don't have one yet.
  • Google GCP Service Account: Use this link and follow instructions to create a GCP service account and token file.
  • Terraform: Used to provision the server and cluster in Google GCP.

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the GCP folder containing the terraform files by executing cd quickstart/rancher/gcp.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • gcp_account_json - GCP service account file path and file name
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the GCP Quickstart Readme for more information. Suggestions include:

    • gcp_region - Google GCP region, choose the closest instead of the default (us-east4)
    • gcp_zone - Google GCP zone, choose the closest instead of the default (us-east4-a)
    • prefix - Prefix for all created resources
    • machine_type - Compute instance size used, minimum is n1-standard-1 but n1-standard-2 or n1-standard-4 could be used if within budget

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/gcp.

Result​

Two Kubernetes clusters are deployed into your GCP account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/gcp folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html b/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html index c190164b873..a11f9b9fbe1 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html @@ -5,13 +5,13 @@ Helm CLI Quick Start | Rancher Manager - +
Version: v2.6

Helm CLI Quick Start

These instructions capture a quick way to set up a proof-of-concept Rancher installation.

These instructions assume you have a Linux virtual machine that you will communicate with from your local workstation. Rancher will be installed on the Linux machine. You will need to retrieve the IP address of that machine so that you can access Rancher from your local workstation. Rancher is designed to manage Kubernetes clusters remotely, so any Kubernetes cluster that Rancher manages in the future will also need to be able to reach this IP address.

We don't recommend installing Rancher locally because it creates a networking problem. Installing Rancher on localhost does not allow Rancher to communicate with downstream Kubernetes clusters, so on localhost you wouldn't be able to test Rancher's cluster provisioning or cluster management functionality.

Your Linux machine can be anywhere. It could be an Amazon EC2 instance, a Digital Ocean droplet, or an Azure virtual machine, to name a few examples. Other Rancher docs often use 'node' as a generic term for all of these. One possible way to deploy a Linux machine is by setting up an Amazon EC2 instance as shown in this tutorial.

The full installation requirements are here.

Install K3s on Linux​

Install a K3s cluster by running this command on the Linux machine:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="***" sh -s - server --cluster-init

Rancher needs to be installed on a supported Kubernetes version. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script. Refer to the support maintenance terms.

Using --cluster-init allows K3s to use embedded etcd as the datastore and has the ability to convert to an HA setup. Refer to High Availability with Embedded DB.

Save the IP of the Linux machine.

Save the kubeconfig to your workstation​

The kubeconfig file is important for accessing the Kubernetes cluster. Copy the file at /etc/rancher/k3s/k3s.yaml from the Linux machine and save it to your local workstation in the directory ~/.kube/config. One way to do this is by using the scp tool and run this command on your local machine:

scp root@<IP_OF_LINUX_MACHINE>:/etc/rancher/k3s/k3s.yaml ~/.kube/config

Edit the Rancher server URL in the kubeconfig​

In the kubeconfig file, you will need to change the value of the server field to <IP_OF_LINUX_NODE>:6443. The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443. This edit is needed so that when you run Helm or kubectl commands from your local workstation, you will be able to communicate with the Kubernetes cluster that Rancher will be installed on.

One way to open the kubeconfig file for editing is to use Vim:

vi ~/.kube/config

Press i to put Vim in insert mode. To save your work, press Esc. Then press :wq and press Enter.

Install Rancher with Helm​

Then from your local workstation, run the following commands. You will need to have kubectl and helm. installed.

helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

kubectl create namespace cattle-system

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml

helm repo add jetstack https://charts.jetstack.io

helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.7.1

# Windows Powershell
helm install cert-manager jetstack/cert-manager `
  --namespace cert-manager `
  --create-namespace `
  --version v1.7.1

The final command to install Rancher is below. The command requires a domain name that forwards traffic to the Linux machine. For the sake of simplicity in this tutorial, you can use a fake domain name to create your proof-of-concept. An example of a fake domain name would be <IP_OF_LINUX_NODE>.sslip.io.

To install a specific Rancher version, use the --version flag (e.g., --version 2.6.6). Otherwise, the latest Rancher is installed by default. Refer to Choosing a Rancher Version.

helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=<IP_OF_LINUX_NODE>.sslip.io \
  --set replicas=1 \
  --set bootstrapPassword=<PASSWORD_FOR_RANCHER_ADMIN>

# Windows Powershell
helm install rancher rancher-latest/rancher `
  --namespace cattle-system `
  --set hostname=<IP_OF_LINUX_NODE>.sslip.io `
  --set replicas=1 `
  --set bootstrapPassword=<PASSWORD_FOR_RANCHER_ADMIN>

Now if you navigate to <IP_OF_LINUX_NODE>.sslip.io in a web browser, you should see the Rancher UI.

To make these instructions simple, we used a fake domain name and self-signed certificates to do this installation. Therefore, you will probably need to add a security exception to your web browser to see the Rancher UI. Note that for production installs, you would need a high-availability setup with a load balancer, a real domain name and real certificates.

These instructions also left out the full installation requirements and other installation options. If you have any issues with these steps, refer to the full Helm CLI installation docs.

To launch new Kubernetes clusters with your new Rancher server, you may need to set up cloud credentials in Rancher. For more information, see Launching Kubernetes clusters with Rancher.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.html b/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.html index c359b709496..8afd75cabf2 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/hetzner-cloud.html @@ -5,7 +5,7 @@ Rancher Hetzner Cloud Quick Start Guide | Rancher Manager - + @@ -13,7 +13,7 @@
Version: v2.6

Rancher Hetzner Cloud Quick Start Guide

The following steps will quickly deploy a Rancher server on Hetzner Cloud in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to Hetzner Cloud will incur charges.

  • Hetzner Cloud Account: You will require an account on Hetzner as this is where the server and cluster will run.
  • Hetzner API Access Key: Use these instructions to create a Hetzner Cloud API Key if you don't have one.
  • Terraform: Used to provision the server and cluster to Hetzner.

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the Hetzner folder containing the terraform files by executing cd quickstart/rancher/hcloud.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • hcloud_token - Hetzner API access key
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the Hetzner Quickstart Readme for more information. Suggestions include:

    • prefix - Prefix for all created resources
    • instance_type - Instance type, minimum required is cx21
    • hcloud_location - Hetzner Cloud location, choose the closest instead of the default (fsn1)

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/hcloud.

Result​

Two Kubernetes clusters are deployed into your Hetzner account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/hcloud folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.html b/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.html index 79bfb01d9bb..0ddfda0bbf7 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/outscale-qs.html @@ -5,7 +5,7 @@ Rancher Outscale Quick Start Guide | Rancher Manager - + @@ -13,7 +13,7 @@
Version: v2.6

Rancher Outscale Quick Start Guide

The following steps will quickly deploy a Rancher server on Outscale in a single-node K3s Kubernetes cluster, with a single-node downstream Kubernetes cluster attached.

note

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

caution

Deploying to Outscale will incur charges.

  • Outscale Account: You will require an account on Outscale as this is where the server and cluster will run.
  • Outscale Access Key: Use these instructions to create an Outscale Access Key if you don't have one.
  • Terraform: Used to provision the server and cluster in Outscale.

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the Outscale folder containing the terraform files by executing cd quickstart/rancher/outscale.

  3. Rename the terraform.tfvars.example file to terraform.tfvars.

  4. Edit terraform.tfvars and customize the following variables:

    • access_key_id - Outscale access key
    • secret_key_id - Outscale secret key
    • rancher_server_admin_password - Admin password for created Rancher server

  5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the Outscale Quickstart Readme for more information. Suggestions include:

    - `region` - Outscale region, choose the closest instead of the default (`eu-west-2`)
    - `prefix` - Prefix for all created resources
    - `instance_type` - Instance type, minimum required is `tinav3.c2r4p3`

  6. Run terraform init.

  7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

    Apply complete! Resources: 21 added, 0 changed, 0 destroyed.

    Outputs:

    rancher_node_ip = xx.xx.xx.xx
    rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
    workload_node_ip = yy.yy.yy.yy

  8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

  9. ssh to the Rancher Server using the id_rsa key generated in quickstart/rancher/outscale.

Result​

Two Kubernetes clusters are deployed into your Outscale account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/outscale folder, execute terraform destroy --auto-approve.

  2. Wait for confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html b/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html index 02dcb6bfe46..755f056a659 100644 --- a/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html +++ b/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html @@ -5,13 +5,13 @@ Vagrant Quick Start | Rancher Manager - +
Version: v2.6

Vagrant Quick Start

The following steps quickly deploy a Rancher Server with a single node cluster attached.

caution

The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

Prerequisites​

  • Vagrant: Vagrant is required as this is used to provision the machine based on the Vagrantfile.
  • Virtualbox: The virtual machines that Vagrant provisions need to be provisioned to VirtualBox.
  • At least 4GB of free RAM.

Note​

  • Vagrant will require plugins to create VirtualBox VMs. Install them with the following commands:

    vagrant plugin install vagrant-vboxmanage

    vagrant plugin install vagrant-vbguest

Getting Started​

  1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

  2. Go into the folder containing the Vagrantfile by executing cd quickstart/rancher/vagrant.

  3. Optional: Edit config.yaml to:

    • Change the number of nodes and the memory allocations, if required. (node.count, node.cpus, node.memory)
    • Change the password of the admin user for logging into Rancher. (admin_password)

  4. To initiate the creation of the environment run, vagrant up --provider=virtualbox.

  5. Once provisioning finishes, go to https://192.168.56.101 in the browser. The default user/password is admin/adminPassword.

Result: Rancher Server and your Kubernetes cluster is installed on VirtualBox.

What's Next?​

Use Rancher to create a deployment. For more information, see Creating Deployments.

Destroying the Environment​

  1. From the quickstart/rancher/vagrant folder execute vagrant destroy -f.

  2. Wait for the confirmation that all resources have been destroyed.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-workloads/nodeports.html b/getting-started/quick-start-guides/deploy-workloads/nodeports.html index a9884f1edab..84e9903c499 100644 --- a/getting-started/quick-start-guides/deploy-workloads/nodeports.html +++ b/getting-started/quick-start-guides/deploy-workloads/nodeports.html @@ -5,13 +5,13 @@ Workload with NodePort Quick Start | Rancher Manager - +
Version: v2.6

Workload with NodePort Quick Start

Prerequisite​

You have a running cluster with at least 1 node.

1. Deploying a Workload​

You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

For this workload, you'll be deploying the application Rancher Hello-World.

  1. Click ☰ > Cluster Management.

  2. From the Clusters page, go to the cluster where the workload should be deployed and click Explore.

  3. Click Workload.

  4. Click Create.

  5. Enter a Name for your workload.

  6. From the Container Image field, enter rancher/hello-world. This field is case-sensitive.

  7. Click Add Port.

  8. From the Service Type drop-down, make sure that NodePort is selected.

    As a dropdown, NodePort (On every node selected)

  9. From the Publish the container port field, enter port 80.

    Publish the container port, 80 entered

  10. Click Create.

Result:

  • Your workload is deployed. This process might take a few minutes to complete.
  • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

2. Viewing Your Application​

From the Workloads page, click the link underneath your workload. If your deployment succeeded, your application opens.

Attention: Cloud-Hosted Sandboxes​

When using a cloud-hosted virtual machine, you may not have access to the port running the container. In this event, you can test Nginx in an ssh session on the local machine using Execute Shell. Use the port number after the : in the link under your workload if available, which is 31568 in this example.

gettingstarted@rancher:~$ curl http://localhost:31568
<!DOCTYPE html>
<html>
  <head>
    <title>Rancher</title>
    <link rel="icon" href="img/favicon.png">
    <style>
      body {
        background-color: white;
        text-align: center;
        padding: 50px;
        font-family: "Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;
      }
      button {
          background-color: #0075a8;
          border: none;
          color: white;
          padding: 15px 32px;
          text-align: center;
          text-decoration: none;
          display: inline-block;
          font-size: 16px;
      }

      #logo {
        margin-bottom: 40px;
      }
    </style>
  </head>
  <body>
    <img id="logo" src="img/rancher-logo.svg" alt="Rancher logo" width=400 />
    <h1>Hello world!</h1>
    <h3>My hostname is hello-world-66b4b9d88b-78bhx</h3>
    <div id='Services'>
      <h3>k8s services found 2</h3>

      <b>INGRESS_D1E1A394F61C108633C4BD37AEDDE757</b> tcp://10.43.203.31:80<br />

      <b>KUBERNETES</b> tcp://10.43.0.1:443<br />

    </div>
    <br />

    <div id='rancherLinks' class="row social">
      <a class="p-a-xs" href="https://rancher.com/docs"><img src="img/favicon.png" alt="Docs" height="25" width="25"></a>
      <a class="p-a-xs" href="https://slack.rancher.io/"><img src="img/icon-slack.svg" alt="slack" height="25" width="25"></a>
      <a class="p-a-xs" href="https://github.com/rancher/rancher"><img src="img/icon-github.svg" alt="github" height="25" width="25"></a>
      <a class="p-a-xs" href="https://twitter.com/Rancher_Labs"><img src="img/icon-twitter.svg" alt="twitter" height="25" width="25"></a>
      <a class="p-a-xs" href="https://www.facebook.com/rancherlabs/"><img src="img/icon-facebook.svg" alt="facebook" height="25" width="25"></a>
      <a class="p-a-xs" href="https://www.linkedin.com/groups/6977008/profile"><img src="img/icon-linkedin.svg" height="25" alt="linkedin" width="25"></a>
    </div>
    <br />
    <button class='button' onclick='myFunction()'>Show request details</button>
    <div id="reqInfo" style='display:none'>
      <h3>Request info</h3>
      <b>Host:</b> 172.22.101.111:31411 <br />
      <b>Pod:</b> hello-world-66b4b9d88b-78bhx </b><br />

      <b>Accept:</b> [*/*]<br />

      <b>User-Agent:</b> [curl/7.47.0]<br />

    </div>
    <br />
    <script>
      function myFunction() {
          var x = document.getElementById("reqInfo");
          if (x.style.display === "none") {
              x.style.display = "block";
          } else {
              x.style.display = "none";
          }
      }
    </script>
  </body>
</html>
gettingstarted@rancher:~$

Finished​

Congratulations! You have successfully deployed a workload exposed via a NodePort.

What's Next?​

When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html b/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html index 5f4fe2084f1..61d18910b66 100644 --- a/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html +++ b/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html @@ -5,13 +5,13 @@ Workload with Ingress Quick Start | Rancher Manager - +
Version: v2.6

Workload with Ingress Quick Start

Prerequisite​

You have a running cluster with at least 1 node.

1. Deploying a Workload​

You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

For this workload, you'll be deploying the application Rancher Hello-World.

  1. Click ☰ > Cluster Management.
  2. Go to the cluster that you created and click Explore.
  3. Click Workload.
  4. Click Create.
  5. Click Deployment.
  6. Enter a Name for your workload.
  7. From the Docker Image field, enter rancher/hello-world. This field is case-sensitive.
  8. Click Add Port and enter 80 in the Private Container Port field. Adding a port enables access to the application inside and outside of the cluster. For more information, see Services.
  9. Click Create.

Result:

  • Your workload is deployed. This process might take a few minutes to complete.
  • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

2. Expose The Application Via An Ingress​

Now that the application is up and running, it needs to be exposed so that other services can connect.

  1. Click ☰ > Cluster Management.

  2. Go to the cluster that you created and click Explore.

  3. Click Service Discovery > Ingresses.

  4. Click Create.

  5. When choosing Namespace, ensure it is the same as the one used when you created your deployment. Otherwise, your deployment will not be available when you attempt to select Target Service, as in Step 8 below.

  6. Enter a Name, such as hello.

  7. Specify your Path, such as /hello.

  8. In the Target Service field, drop down the list and choose the name that you set for your service.

  9. In the Port field, drop down the list and select 80.

  10. Click Create at the bottom right.

Result: The application is assigned a sslip.io address and exposed. It may take a minute or two to populate.

View Your Application​

From the Deployments page, find the Endpoints column for your deployment and click on an endpoint. The endpoints available will depend on how you configured the port you added to your deployment. For endpoints where you do not see a randomly assigned port, append the path you specified when creating the ingress to the IP address. For example, if your endpoint looks like xxx.xxx.xxx.xxx or https://xxx.xxx.xxx.xxx change it to xxx.xxx.xxx.xxx/hello or https://xxx.xxx.xxx.xxx/hello.

Your application will open in a separate window.

Finished​

Congratulations! You have successfully deployed a workload exposed via an ingress.

What's Next?​

When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides.html b/how-to-guides.html index ba6b5fb6337..dbfdbac3c67 100644 --- a/how-to-guides.html +++ b/how-to-guides.html @@ -5,13 +5,13 @@ How-to Guides | Rancher Manager - +
Version: v2.6

How-to Guides

How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html index bbd5f8a7d53..3bba95a7531 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html @@ -5,13 +5,13 @@ Configure Active Directory (AD) | Rancher Manager - +
Version: v2.6

Configure Active Directory (AD)

If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.

Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the OpenLDAP authentication integration.

note

Before you start, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

Prerequisites​

You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.

Usually a (non-admin) Domain User account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.

Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least Read and List Content permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.

Using TLS?

  • If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

  • Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15.

    • The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0".

    • To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting GODEBUG=x509ignoreCN=0 as an environment variable to Rancher server container.

Configuration Steps​

Open Active Directory Configuration​

  1. Log into the Rancher UI using the initial local admin account.
  2. In the top left corner, click ☰ > Users & Authentication.
  3. In the left navigation menu, click Auth Provider.
  4. Click ActiveDirectory. The Authentication Provider: ActiveDirectory form will be displayed.
  5. Fill out the form. For help, refer to the details on configuration options below.
  6. Click Enable.

Configure Active Directory Server Settings​

In the section titled 1. Configure an Active Directory server, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.

note

If you are unsure about the correct values to enter in the user/group Search Base field, please refer to Identify Search Base and Schema using ldapsearch.

Table 1: AD Server parameters

ParameterDescription
HostnameSpecify the hostname or IP address of the AD server
PortSpecify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS).
Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the AD server unreachable.
Service Account UsernameEnter the username of an AD account with read-only access to your domain partition (see Prerequisites). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com").
Service Account PasswordThe password for the service account.
Default Login DomainWhen you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field must be left empty.
User Search BaseThe Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".

Configure User/Group Schema​

In the section titled 2. Customize Schema you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.

Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.

note

If you are unfamiliar with the schema used in your Active Directory domain, please refer to Identify Search Base and Schema using ldapsearch to determine the correct configuration values.

User Schema​

The table below details the parameters for the user schema section configuration.

Table 2: User schema configuration parameters

ParameterDescription
Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
Username AttributeThe user attribute whose value is suitable as a display name.
Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to userPrincipalName. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually sAMAccountName.
User Member AttributeThe attribute containing the groups that a user is a member of.
Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to userPrincipalName.
Search FilterThis filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io)). Note: If the search filter does not use valid AD search syntax, the list of users will be empty.
User Enabled AttributeThe attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard userAccountControl.
Disabled Status BitmaskThis is the value of the User Enabled Attribute designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see here).

Group Schema​

The table below details the parameters for the group schema configuration.

Table 3: Group schema configuration parameters

ParameterDescription
Object ClassThe name of the object class used for group objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
Name AttributeThe group attribute whose value is suitable for a display name.
Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
Search AttributeAttribute used to construct search filters when adding groups to clusters or projects. See description of user schema Search Attribute.
Search FilterThis filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use valid AD search syntax, the list of groups will be empty.
Group DN AttributeThe name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See User Member Attribute.
Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible to avoid potential performance issues when there is a large amount of nested memberships).

Test Authentication​

Once you have completed the configuration, proceed by testing the connection to the AD server using your AD admin account. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin.

note

The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.

  1. Enter the username and password for the AD account that should be mapped to the local principal account.
  2. Click Authenticate with Active Directory to finalise the setup.

Result:

  • Active Directory authentication has been enabled.
  • You have been signed into Rancher as administrator using the provided AD credentials.
note

You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

Annex: Identify Search Base and Schema using ldapsearch​

In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server.

The ldapsearch tool allows you to query your AD server to learn about the schema used for user and group objects.

For the purpose of the example commands provided below we will assume:

  • The Active Directory server has a hostname of ad.acme.com
  • The server is listening for unencrypted connections on port 389
  • The Active Directory domain is acme
  • You have a valid AD account with the username jdoe and password secret

Identify Search Base​

First we will use ldapsearch to identify the Distinguished Name (DN) of the parent node(s) for users and groups:

$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"

This command performs an LDAP search with the search base set to the domain root (-b "dc=acme,dc=com") and a filter targeting the user account (sAMAccountNam=jdoe), returning the attributes for said user:

Since in this case the user's DN is CN=John Doe,CN=Users,DC=acme,DC=com [5], we should configure the User Search Base with the parent node DN CN=Users,DC=acme,DC=com.

Similarly, based on the DN of the group referenced in the memberOf attribute [4], the correct value for the Group Search Base would be the parent node of that value, i.e., OU=Groups,DC=acme,DC=com.

Identify User Schema​

The output of the above ldapsearch query also allows to determine the correct values to use in the user schema configuration:

  • Object Class: person [1]
  • Username Attribute: name [2]
  • Login Attribute: sAMAccountName [3]
  • User Member Attribute: memberOf [4]
note

If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the Login Attribute to userPrincipalName instead.

We'll also set the Search Attribute parameter to sAMAccountName|name. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.

Identify Group Schema​

Next, we'll query one of the groups associated with this user, in this case CN=examplegroup,OU=Groups,DC=acme,DC=com:

$ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
-h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
-s sub "CN=examplegroup"

This command will inform us on the attributes used for group objects:

Again, this allows us to determine the correct values to enter in the group schema configuration:

  • Object Class: group [1]
  • Name Attribute: name [2]
  • Group Member Mapping Attribute: member [3]
  • Search Attribute: sAMAccountName [4]

Looking at the value of the member attribute, we can see that it contains the DN of the referenced user. This corresponds to the distinguishedName attribute in our user object. Accordingly will have to set the value of the Group Member User Attribute parameter to this attribute.

In the same way, we can observe that the value in the memberOf attribute in the user object corresponds to the distinguishedName [5] of the group. We therefore need to set the value for the Group DN Attribute parameter to this attribute.

Annex: Troubleshooting​

If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html index a3912bad891..64726f54503 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html @@ -5,7 +5,7 @@ Configure Azure AD | Rancher Manager - + @@ -13,7 +13,7 @@
Version: v2.6

Configure Azure AD

Microsoft Graph API​

Microsoft Graph API is now the flow through which you will set up Azure AD. The below sections will assist new users in configuring Azure AD with a new instance as well as assist existing Azure app owners in migrating to the new flow.

New User Setup​

If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.

Notes
  • Azure AD integration only supports Service Provider initiated logins.
  • Most of this procedure takes place from the Microsoft Azure Portal.

Azure Active Directory Configuration Outline​

Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.

tip

Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.

1. Register Rancher with Azure​

Before enabling Azure AD within Rancher, you must register Rancher with Azure.

  1. Log in to Microsoft Azure as an administrative user. Configuration in future steps requires administrative access rights.

  2. Use search to open the App registrations service.

    Open App Registrations

  3. Click New registrations and complete the Create form.

    New App Registration

    1. Enter a Name (something like Rancher).

    2. From Supported account types, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.

      note

      In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below.

    3. In the Redirect URI section, make sure Web is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: <MY_RANCHER_URL>/verify-auth-azure.

      tip

      You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web).

    4. Click Register.

note

It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.

2. Create a new client secret​

From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.

  1. Use search to open App registrations services. Then open the entry for Rancher that you created in the last procedure.

    Open Rancher Registration

  2. From the navigation pane on left, click Certificates and Secrets.

  3. Click New client secret. Create new client secret

  4. Enter a Description (something like Rancher).

  5. Select duration for the key from the options under Expires. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.

  6. Click Add (you don't need to enter a value—it will automatically populate after you save).

  7. Copy the key value and save it to an empty text file.

    You'll enter this key into the Rancher UI later as your Application Secret.

    You won't be able to access the key value again within the Azure UI.

3. Set Required Permissions for Rancher​

Next, set API permissions for Rancher within Azure.

caution

Ensure that you set the permissions of type Application and NOT Delegated. Otherwise, you may not be able to login to Azure AD. This issue will persist even after you disable/re-enable Azure AD and will require an hour wait, or manual deletion of a cache value to resolve.

  1. From the navigation pane on left, select API permissions.

    Open Required Permissions

  2. Click Add a permission.

  3. From the Microsoft Graph, select the following Application Permissions:

    • Group.Read.All
    • User.Read.All

    Select API Permissions

  4. Return to API permissions in the left nav bar. From there, click Grant admin consent. Then click Yes.

    note

    You must be signed in as an Azure administrator to successfully save your permission settings.

4. Copy Azure Application Data​

As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.

  1. Obtain your Rancher Tenant ID.

    1. Use search to open App registrations.

    Open App Registrations

    1. Find the entry you created for Rancher.

    2. Copy the Directory ID and paste it into your text file.

    Tenant ID

    • You'll paste this value into Rancher as your Tenant ID.

  2. Obtain your Rancher Application (Client) ID.

    2.1. Use search to open App registrations (if not already there).

    2.2. In Overview, find the entry you created for Rancher.

    2.3. Copy the Application (Client) ID and paste it to your text file.

    Application ID

  3. Your endpoint options will typically be Standard and China. With these options, you need only enter the Tenant ID, Application ID, and Application Secret (Rancher will take care of the rest).

Standard Endpoint Options

For Custom Endpoints:

Warning: Custom Endpoints are not supported nor fully tested by Rancher.

You will need to also manually enter the Graph, Token, and Auth Endpoints.

  • From App registrations, click Endpoints:

Click Endpoints

  • Copy the following endpoints to your clipboard and paste them into your text file (these values will be your Rancher endpoint values). Make sure to copy the v1 version of the endpoints.
    • Microsoft Graph API endpoint (Graph Endpoint)
    • OAuth 2.0 token endpoint (v1) (Token Endpoint)
    • OAuth 2.0 authorization endpoint (v1) (Auth Endpoint)

5. Configure Azure AD in Rancher​

From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.

Enter the values that you copied to your text file.

  1. Log into Rancher.

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Click AzureAD.

  5. Complete the Configure Azure AD Account form using the information you copied while completing Copy Azure Application Data.

    The following table maps the values you copied in the Azure portal to the fields in Rancher:

    Rancher FieldAzure Value
    Tenant IDDirectory ID
    Application IDApplication ID
    Application SecretKey Value
    Endpointhttps://login.microsoftonline.com/

For Custom Endpoints:

The following table maps the custom config values you copied in the Azure portal to the fields in Rancher:

Rancher FieldAzure Value
Graph EndpointMicrosoft Graph API Endpoint
Token EndpointOAuth 2.0 Token Endpoint
Auth EndpointOAuth 2.0 Authorization Endpoint

Important: When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL, like below:

https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c
  1. Click Enable.

Result: Azure Active Directory authentication is configured.

Migrating from Azure AD Graph API to Microsoft Graph API​

Since Azure AD Graph API was deprecated in June 2022 and will be retired at the end of 2022, users should update their Azure AD App to use the new Microsoft Graph API in Rancher.

Updating Endpoints in the Rancher UI​

Important: Admins should create a backup right before they commit to the endpoint migration in Step 4 below.

  1. Update the permissions of your Azure AD app registration as described here. This is critical.

  2. Log into Rancher.

  3. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so.

    Rancher UI Banner

  4. To complete the move to the new Microsoft Graph API, click Update Endpoint.

    Note: Ensure that your Azure app has a new set of permissions before starting the update.

    Update Endpoint

  5. When you receive the pop-up warning message, click Update.

    Azure Update Pop-up

  6. Refer to the tables below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually.

Air-Gapped Environments​

In air-gapped environments, admins should ensure that their endpoints are whitelisted since the Graph Endpoint URL is changing.

Rolling Back the Migration​

If you need to roll back your migration, please note the following:

  1. Admins are encouraged to use the proper restore process if they want to go back. Please see backup docs, restore docs, and examples for reference.

  2. Azure app owners who want to rotate the Application Secret will need to also rotate it in Rancher as Rancher does not automatically update the Application Secret when it is changed in Azure. In Rancher, note that it is stored in a Kubernetes secret called azureadconfig-applicationsecret which is in the cattle-global-data namespace.

  3. Caution: If admins upgrade to Rancher v2.6.7 with an existing Azure AD setup and choose to disable the auth provider, they won't be able to restore the previous setup and also will not be able to set up Azure AD anew using the old flow. Admins will then need to register again with the new auth flow. Rancher now uses the new Graph API and, therefore, users need set up the proper permissions in the Azure portal.

Global:​

Rancher FieldDeprecated Endpoints
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.windows.net/
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/token
Rancher FieldNew Endpoints
Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.microsoftonline.com/
Graph Endpointhttps://graph.microsoft.com
Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

China:​

Rancher FieldDeprecated Endpoints
Auth Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/authorize
Endpointhttps://login.chinacloudapi.cn/
Graph Endpointhttps://graph.chinacloudapi.cn/
Token Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/token
Rancher FieldNew Endpoints
Auth Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize
Endpointhttps://login.partner.microsoftonline.cn/
Graph Endpointhttps://microsoftgraph.chinacloudapi.cn
Token Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html index 7e0bab008f4..f10c3c0976e 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html @@ -5,13 +5,13 @@ Configure FreeIPA | Rancher Manager - +
Version: v2.6

Configure FreeIPA

If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.

Prerequisites:

  1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Click FreeIPA.

  5. Complete the Configure an FreeIPA server form.

    You may need to log in to your domain controller to find the information requested in the form.

    Using TLS?

    If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.

    User Search Base vs. Group Search Base

    Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.

    • If your users and groups are in the same search base, complete only the User Search Base.
    • If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.

  6. If your FreeIPA deviates from the standard AD schema, complete the Customize Schema form to match it. Otherwise, skip this step.

    Search Attribute

    The Search Attribute field defaults with three specific values: uid|sn|givenName. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.

    The default field value uid|sn|givenName, but you can configure this field to a subset of these fields. The pipe (|) between the fields separates these fields.

    • uid: User ID
    • sn: Last Name
    • givenName: First Name

    With this search attribute, Rancher creates search filters for users and groups, but you cannot add your own search filters in this field.

  7. Enter your FreeIPA username and password in Authenticate with FreeIPA to confirm that Rancher is configured to use FreeIPA authentication.

  8. Click Enable.

Result:

  • FreeIPA authentication is configured.
  • You are signed into Rancher with your FreeIPA account (i.e., the external principal).
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html index 3606eb0b0e6..a1f981a5f92 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html @@ -5,13 +5,13 @@ Configure GitHub | Rancher Manager - +
Version: v2.6

Configure GitHub

In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.

Prerequisites:

Read External Authentication Configuration and Principal Users.

  1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Click GitHub.

  5. Follow the directions displayed to set up a GitHub Application. Rancher redirects you to GitHub to complete registration.

    What's an Authorization Callback URL?

    The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).

    When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.

  6. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.

    Where do I find the Client ID and Client Secret?

    From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.

  7. Click Authenticate with GitHub.

  8. Use the Site Access options to configure the scope of user authorization.

    • Allow any valid Users

      Any GitHub user can access Rancher. We generally discourage use of this setting!

    • Allow members of Clusters, Projects, plus Authorized Users and Organizations

      Any GitHub user or group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any GitHub user or group you add to the Authorized Users and Organizations list may log in to Rancher.

    • Restrict access to only Authorized Users and Organizations

      Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.


  9. Click Enable.

Result:

  • GitHub authentication is configured.
  • You are signed into Rancher with your GitHub account (i.e., the external principal).
Copyright © 2022 SUSE Rancher. All Rights Reserved.
- + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html index a80ad7bf4d6..bbd3ee082fe 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html @@ -5,7 +5,7 @@ Configure Google OAuth | Rancher Manager - + @@ -15,7 +15,7 @@ OAuth Consent Screen
  • Go to Authorized Domains and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to this article.
  • Go to Scopes for Google APIs and make sure email, profile and openid are enabled.

    • Result: Rancher has been added as an authorized domain for the Admin SDK API.

    2. Creating OAuth2 Credentials for the Rancher Server​

    1. Go to the Google API console, select your project, and go to the credentials page.Credentials
    2. On the Create Credentials dropdown, select OAuth client ID.
    3. Click Web application.
    4. Provide a name.
    5. Fill out the Authorized JavaScript origins and Authorized redirect URIs. Note: The Rancher UI page for setting up Google OAuth (available from the Global view under Security > Authentication > Google) provides you the exact links to enter for this step.
    • Under Authorized JavaScript origins, enter your Rancher server URL.
    • Under Authorized redirect URIs, enter your Rancher server URL appended with the path verify-auth. For example, if your URI is https://rancherServer, you will enter https://rancherServer/verify-auth.
    1. Click on Create.
    2. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click Download JSON. Save the file so that you can provide these credentials to Rancher.

    Result: Your OAuth credentials have been successfully created.

    3. Creating Service Account Credentials​

    Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups.

    Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed.

    As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account.

    This section describes how to:

    • Create a service account
    • Create a key for the service account and download the credentials as JSON
    1. Click here and select your project for which you generated OAuth credentials.
    2. Click on Create Service Account.
    3. Enter a name and click Create. Service account creation Step 1
    4. Don't provide any roles on the Service account permissions page and click ContinueService account creation Step 2
    5. Click on Create Key and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher. Service account creation Step 3

    Result: Your service account is created.

    4. Register the Service Account Key as an OAuth Client​

    You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups.

    Using the Unique ID of the service account key, register it as an Oauth Client using the following steps:

    1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click Unique ID and click OK. This will add a Unique ID column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field Key ID.

      Service account Unique ID

    2. Go to the Domain-wide Delegation page.

    3. Add the Unique ID obtained in the previous step in the Client Name field.

    4. In the One or More API Scopes field, add the following scopes:

      openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly

    5. Click Authorize.

    Result: The service account is registered as an OAuth client in your G Suite account.

    Configuring Google OAuth in Rancher

    1. Sign into Rancher using a local user assigned the administrator role. This user is also called the local principal.
    2. In the top left corner, click ☰ > Users & Authentication.
    3. In the left navigation menu, click Auth Provider.
    4. Click Google. The instructions in the UI cover the steps to set up authentication with Google OAuth.
      1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
      2. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
      3. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
      • Step One is about adding Rancher as an authorized domain, which we already covered in this section.
      • For Step Two, provide the OAuth credentials JSON that you downloaded after completing this section. You can upload the file or paste the contents into the OAuth Credentials field.
      • For Step Three, provide the service account credentials JSON that downloaded at the end of this section. The credentials will only work if you successfully registered the service account key as an OAuth client in your G Suite account.
    5. Click Authenticate with Google.
    6. Click Enable.

    Result: Google authentication is successfully configured.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.html index 6d47c146dc2..6e57a9074ec 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-oidc.html @@ -5,13 +5,13 @@ Configure Keycloak (OIDC) | Rancher Manager - +
    Version: v2.6

    Configure Keycloak (OIDC)

    If your organization uses Keycloak Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials. Rancher supports integration with Keycloak using the OpenID Connect (OIDC) protocol and the SAML protocol. Both implementations are functionally equivalent when used with Rancher. This page describes the process to configure Rancher to work with Keycloak using the OIDC protocol.

    If you prefer to use Keycloak with the SAML protocol instead, refer to this page.

    If you have an existing configuration using the SAML protocol and want to switch to the OIDC protocol, refer to this section.

    Prerequisites​

    • On Rancher, Keycloak (SAML) is disabled.

    • You must have a Keycloak IdP Server configured.

    • In Keycloak, create a new OIDC client, with the settings below. See the Keycloak documentation for help.

      SettingValue
      Client ID<CLIENT_ID> (e.g. rancher)
      Name<CLIENT_NAME> (e.g. rancher)
      Client Protocolopenid-connect
      Access Typeconfidential
      Valid Redirect URIhttps://yourRancherHostURL/verify-auth

    • In the new OIDC client, create Mappers to expose the users fields.

      • Create a new "Groups Mapper" with the settings below.

        SettingValue
        NameGroups Mapper
        Mapper TypeGroup Membership
        Token Claim Namegroups
        Add to ID tokenOFF
        Add to access tokenOFF
        Add to user infoON

      • Create a new "Client Audience" with the settings below.

        SettingValue
        NameClient Audience
        Mapper TypeAudience
        Included Client Audience<CLIENT_NAME>
        Add to access tokenON

      • Create a new "Groups Path" with the settings below.

        SettingValue
        NameGroup Path
        Mapper TypeGroup Membership
        Token Claim Namefull_group_path
        Full group pathON
        Add to user infoON

    Configuring Keycloak in Rancher​

    1. In the Rancher UI, click ☰ > Users & Authentication.

    2. In the left navigation bar, click Auth Provider.

    3. Select Keycloak (OIDC).

    4. Complete the Configure a Keycloak OIDC account form. For help with filling the form, see the configuration reference.

    5. After you complete the Configure a Keycloak OIDC account form, click Enable.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

      note

      You may need to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign into Rancher using their Keycloak logins.

    Configuration Reference​

    FieldDescription
    Client IDThe Client ID of your Keycloak client.
    Client SecretThe generated Secret of your Keycloak client. In the Keycloak console, select Clients, select the client you created, select the Credentials tab and copy the value of the Secret field.
    Private Key / CertificateA key/certificate pair to create a secure shell between Rancher and your IdP. Required if HTTPS/SSL is enabled on your Keycloak server.
    EndpointsChoose whether to use the generated values for the Rancher URL, Issue, and Auth Endpoint fields or to provide manual overrides if incorrect.
    Keycloak URLThe URL for your Keycloak server.
    Keycloak RealmThe name of the realm in which the Keycloak client was created in.
    Rancher URLThe URL for your Rancher Server.
    IssuerThe URL of your IdP.
    Auth EndpointThe URL where users are redirected to authenticate.

    Migrating from SAML to OIDC​

    This section describes the process to transition from using Rancher with Keycloak (SAML) to Keycloak (OIDC).

    Reconfigure Keycloak​

    1. Change the existing client to use the OIDC protocol. In the Keycloak console, select Clients, select the SAML client to migrate, select the Settings tab, change Client Protocol from saml to openid-connect, and click Save

    2. Verify the Valid Redirect URIs are still valid.

    3. Select the Mappers tab and create a new Mapper with the settings below.

      SettingValue
      NameGroups Mapper
      Mapper TypeGroup Membership
      Token Claim Namegroups
      Add to ID tokenON
      Add to access tokenON
      Add to user infoON

    Reconfigure Rancher​

    Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first disabled.

    1. In the Rancher UI, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Auth Provider.
    3. Select Keycloak (SAML).
    4. Click Disable.

    Configure Rancher to use Keycloak (OIDC) by following the steps in this section.

    note

    After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated.

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration options of your OIDC client. You may also inspect the Rancher logs to help pinpoint what's causing issues. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    All Keycloak related log entries will be prepended with either [generic oidc] or [keycloak oidc].

    You are not redirected to Keycloak​

    When you fill the Configure a Keycloak OIDC account form and click on Enable, you are not redirected to your IdP.

    • Verify your Keycloak client configuration.

    The generated Issuer and Auth Endpoint are incorrect​

    • On the Configure a Keycloak OIDC account form, change Endpoints to Specify (advanced) and override the Issuer and Auth Endpoint values. To find the values, go to the Keycloak console and select Realm Settings, select the General tab, and click OpenID Endpoint Configuration. The JSON output will display values for issuer and authorization_endpoint.

    Keycloak Error: "Invalid grant_type"​

    • In some cases, this error message may be misleading and is actually caused by setting the Valid Redirect URI incorrectly.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.html index 4c16f7a267e..2176f039bdc 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak-saml.html @@ -5,7 +5,7 @@ Configure Keycloak (SAML) | Rancher Manager - + @@ -15,7 +15,7 @@

    Getting the IDP Metadata​

    To get the IDP metadata, export a metadata.xml file from your Keycloak client. From the Installation tab, choose the SAML Metadata IDPSSODescriptor format option and download your file.

    Configuring Keycloak in Rancher​

    1. In the top left corner, click ☰ > Users & Authentication.

    2. In the left navigation menu, click Auth Provider.

    3. Click Keycloak SAML.

    4. Complete the Configure Keycloak Account form. For help with filling the form, see the configuration reference.

    5. After you complete the Configure a Keycloak Account form, click Enable.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

      note

      You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    Configuration Reference​

    FieldDescription
    Display Name FieldThe attribute that contains the display name of users.

    Example: givenName
    User Name FieldThe attribute that contains the user name/given name.

    Example: email
    UID FieldAn attribute that is unique to every user.

    Example: email
    Groups FieldMake entries for managing group memberships.

    Example: member
    Entity ID FieldThe ID that needs to be configured as a client ID in the Keycloak client.

    Default: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata
    Rancher API HostThe URL for your Rancher Server.
    Private Key / CertificateA key/certificate pair to create a secure shell between Rancher and your IdP.
    IDP-metadataThe metadata.xml file that you exported from your IdP server.
    tip

    You can generate a key/certificate pair using an openssl command. For example:

    openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    You are not redirected to Keycloak​

    When you click on Authenticate with Keycloak, you are not redirected to your IdP.

    • Verify your Keycloak client configuration.
    • Make sure Force Post Binding set to OFF.

    Forbidden message displayed after IdP login​

    You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a Forbidden message afterwards.

    • Check the Rancher debug log.
    • If the log displays ERROR: either the Response or Assertion must be signed, make sure either Sign Documents or Sign assertions is set to ON in your Keycloak client.

    HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata​

    This is usually due to the metadata not being created until a SAML provider is configured. Try configuring and saving keycloak as your SAML provider and then accessing the metadata.

    Keycloak Error: "We're sorry, failed to process response"​

    • Check your Keycloak log.
    • If the log displays failed: org.keycloak.common.VerificationException: Client does not have a public key, set Encrypt Assertions to OFF in your Keycloak client.

    Keycloak Error: "We're sorry, invalid requester"​

    • Check your Keycloak log.
    • If the log displays request validation failed: org.keycloak.common.VerificationException: SigAlg was null, set Client Signature Required to OFF in your Keycloak client.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html index 2c25e1aaec4..90a625a2250 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html @@ -5,13 +5,13 @@ Configure Okta (SAML) | Rancher Manager - +
    Version: v2.6

    Configure Okta (SAML)

    If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

    note

    Okta integration only supports Service Provider initiated logins.

    Prerequisites​

    In Okta, create a SAML Application with the settings below. See the Okta documentation for help.

    SettingValue
    Single Sign on URLhttps://yourRancherHostURL/v1-saml/okta/saml/acs
    Audience URI (SP Entity ID)https://yourRancherHostURL/v1-saml/okta/saml/metadata

    Configuring Okta in Rancher​

    1. In the top left corner, click ☰ > Users & Authentication.

    2. In the left navigation menu, click Auth Provider.

    3. Click Okta.

    4. Complete the Configure Okta Account form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.

      FieldDescription
      Display Name FieldThe attribute name from an attribute statement that contains the display name of users.
      User Name FieldThe attribute name from an attribute statement that contains the user name/given name.
      UID FieldThe attribute name from an attribute statement that is unique to every user.
      Groups FieldThe attribute name in a group attribute statement that exposes your groups.
      Rancher API HostThe URL for your Rancher Server.
      Private Key / CertificateA key/certificate pair used for Assertion Encryption.
      Metadata XMLThe Identity Provider metadata file that you find in the application Sign On section.
      tip

      You can generate a key/certificate pair using an openssl command. For example:

      openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt

    1. After you complete the Configure Okta Account form, click Enable.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.

      note

      If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.

    Result: Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html index 5481875e296..62279017951 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html @@ -5,7 +5,7 @@ Configure PingIdentity (SAML) | Rancher Manager - + @@ -14,7 +14,7 @@ Metadata URL: https://<rancher-server>/v1-saml/ping/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/ping/saml/acs Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
  • Export a metadata.xml file from your IdP Server. For more information, see the PingIdentity documentation.

    1. In the top left corner, click ☰ > Users & Authentication.

    2. In the left navigation menu, click Auth Provider.

    3. Click Ping Identity.

    4. Complete the Configure a Ping Account form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Entity ID Field (optional): The published, protocol-dependent, unique identifier of your partner. This ID defines your organization as the entity operating the server for SAML 2.0 transactions. This ID may have been obtained out-of-band or via a SAML metadata file.

      6. Rancher API Host: Enter the URL for your Rancher Server.

      7. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      8. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Ping Account form, click Enable.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.

      note

      You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html index 45b17f9aba9..f37c5752ca9 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html @@ -5,13 +5,13 @@ Local Authentication | Rancher Manager - +
    Version: v2.6

    Local Authentication

    Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the admin user that logs in to Rancher for the first time is a local user.

    Adding Local Users​

    Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.

    1. In the top left corner, click ☰ > Users & Authentication.
    2. In the left navigation menu, click Users.
    3. Click Create.
    4. Complete the Add User form.
    5. Click Create.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html index 8c6d3cd1906..191f4f04845 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html @@ -5,13 +5,13 @@ Users and Groups | Rancher Manager - +
    Version: v2.6

    Users and Groups

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.

    Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see Role Based Access Control.

    Managing Members​

    When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a local user account, you will not be able to search for GitHub users or groups.

    All users, whether they are local users or from an authentication provider, can be viewed and managed. In the upper left corner, click ☰ > Users & Authentication. In the left navigation bar, click Users.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    User Information​

    Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.

    Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.

    Automatically Refreshing User Information​

    Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh.

    Two settings control this behavior:

    • auth-user-info-max-age-seconds

      This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to 3600 seconds, i.e. 1 hour.

    • auth-user-info-resync-cron

      This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to 0 0 * * *, i.e. once a day at midnight. See the Cron documentation for more information on valid values for this setting.

    To change these settings,

    1. In the upper left corner, click ☰ > Global Settings.
    2. Go to the setting you want to configure and click ⋮ > Edit Setting.
    note

    Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.

    Manually Refreshing User Information​

    If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. On the Users page, click on Refresh Group Memberships.

    Results: Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.

    note

    Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.

    Session Length​

    The default length (TTL) of each user session is adjustable. The default session length is 16 hours.

    1. In the upper left corner, click ☰ > Global Settings.
    2. Go to auth-user-session-ttl-minutes and click ⋮ > Edit Setting.
    3. Enter the amount of time in minutes a session length should last and click Save.

    Result: Users are automatically logged out of Rancher after the set number of minutes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html index 31ad64ef29d..6b7cedb4ef8 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html @@ -5,14 +5,14 @@ 1. Configuring Microsoft AD FS for Rancher | Rancher Manager - +
    Version: v2.6

    1. Configuring Microsoft AD FS for Rancher

    Before configuring Rancher to support AD FS users, you must add Rancher as a relying party trust in AD FS.

    1. Log into your AD server as an administrative user.

    2. Open the AD FS Management console. Select Add Relying Party Trust... from the Actions menu and click Start.

    3. Select Enter data about the relying party manually as the option for obtaining data about the relying party.

    4. Enter your desired Display name for your Relying Party Trust. For example, Rancher.

    5. Select AD FS profile as the configuration profile for your relying party trust.

    6. Leave the optional token encryption certificate empty, as Rancher AD FS will not be using one.

    7. Select Enable support for the SAML 2.0 WebSSO protocol and enter https://<rancher-server>/v1-saml/adfs/saml/acs for the service URL.

    8. Add https://<rancher-server>/v1-saml/adfs/saml/metadata as the Relying party trust identifier.

    9. This tutorial will not cover multi-factor authentication; please refer to the Microsoft documentation if you would like to configure multi-factor authentication.

    10. From Choose Issuance Authorization RUles, you may select either of the options available according to use case. However, for the purposes of this guide, select Permit all users to access this relying party.

    11. After reviewing your settings, select Next to add the relying party trust.

    1. Select Open the Edit Claim Rules... and click Close.

    2. On the Issuance Transform Rules tab, click Add Rule....

    3. Select Send LDAP Attributes as Claims as the Claim rule template.

    4. Set the Claim rule name to your desired name (for example, Rancher Attributes) and select Active Directory as the Attribute store. Create the following mapping to reflect the table below:

      LDAP AttributeOutgoing Claim Type
      Given-NameGiven Name
      User-Principal-NameUPN
      Token-Groups - Qualified by Long Domain NameGroup
      SAM-Account-NameName

      ![](/img/adfs/adfs-add-tcr-2.png)

    5. Download the federationmetadata.xml from your AD server at:

    https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    Result: You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.

    Next: Configuring Rancher for Microsoft AD FS​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html index c9e522b696b..7ee6d015617 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html @@ -5,13 +5,13 @@ 2. Configuring Rancher for Microsoft AD FS | Rancher Manager - +
    Version: v2.6

    2. Configuring Rancher for Microsoft AD FS

    After you complete Configuring Microsoft AD FS for Rancher, enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.

    Important Notes For Configuring Your ADFS Server:
    • The SAML 2.0 WebSSO Protocol Service URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs
    • The Relying Party Trust identifier URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata
    • You must export the federationmetadata.xml file from your AD FS server. This can be found at: https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    1. In the top left corner, click ☰ > Users & Authentication.

    2. In the left navigation menu, click Auth Provider.

    3. Click ADFS.

    4. Complete the Configure AD FS Account form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The configuration section below describe how you can map AD attributes to fields within Rancher.

    5. After you complete the Configure AD FS Account form, click Enable.

      Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.

      note

      You may have to disable your popup blocker to see the AD FS login page.

    Result: Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.

    Configuration

    FieldDescription
    Display Name FieldThe AD attribute that contains the display name of users.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    User Name FieldThe AD attribute that contains the user name/given name.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    UID FieldAn AD attribute that is unique to every user.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
    Groups FieldMake entries for managing group memberships.

    Example: http://schemas.xmlsoap.org/claims/Group
    Rancher API HostThe URL for your Rancher Server.
    Private Key / CertificateThis is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.

    Certificate creation command
    Metadata XMLThe federationmetadata.xml file exported from your AD FS server.

    You can find this file at https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml.
    tip

    You can generate a certificate using an openssl command. For example:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html index a8804565cab..e67255d485d 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html @@ -5,13 +5,13 @@ Group Permissions with Shibboleth and OpenLDAP | Rancher Manager - +
    Version: v2.6

    Group Permissions with Shibboleth and OpenLDAP

    This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.

    Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.

    One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.

    Terminology​

    • Shibboleth is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
    • SAML: Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
    • OpenLDAP: a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
    • IdP or IDP: An identity provider. OpenLDAP is an example of an identity provider.

    Adding OpenLDAP Group Permissions to Rancher Resources​

    The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.

    For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.

    In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.

    When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.

    Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.

    Adding OpenLDAP Group Permissions to Rancher Resources

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html index 0afe51d69d1..25dadd921e3 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html @@ -5,13 +5,13 @@ Cluster Drivers | Rancher Manager - +
    Version: v2.6

    Cluster Drivers

    Cluster drivers are used to create clusters in a hosted Kubernetes provider, such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.

    If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.

    Managing Cluster Drivers​

    Prerequisites:

    To create, edit, or delete cluster drivers, you need one of the following permissions:

    Activating/Deactivating Cluster Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. In the left navigation menu, click Drivers.

    3. On the Cluster Drivers tab, select the driver that you wish to activate or deactivate and click ⋮ > Activate or ⋮ > Deactivate.

    Adding Custom Cluster Drivers​

    If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create hosted kubernetes clusters.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click Drivers.
    3. On the Cluster Drivers tab, click Add Cluster Driver.
    4. Complete the Add Cluster Driver form. Then click Create.

    Developing your own Cluster Driver​

    In order to develop cluster driver to add to Rancher, please refer to our example.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html index fdf96f92eda..f2028169f10 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html @@ -5,13 +5,13 @@ Node Drivers | Rancher Manager - +
    Version: v2.6

    Node Drivers

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Managing Node Drivers​

    Prerequisites:

    To create, edit, or delete drivers, you need one of the following permissions:

    Activating/Deactivating Node Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. In the left navigation menu, click Drivers.

    3. On the Node Drivers tab, select the driver that you wish to activate or deactivate and click ⋮ > Activate or ⋮ > Deactivate.

    Adding Custom Node Drivers​

    If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click Drivers.
    3. On Node Drivers tab, click Add Node Driver.
    4. Complete the Add Node Driver form. Then click Create.

    Developing your own node driver​

    Node drivers are implemented with Docker Machine.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html index b0866715f38..6f04d2d57ae 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html @@ -5,13 +5,13 @@ Access and Sharing | Rancher Manager - +
    Version: v2.6

    Access and Sharing

    If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.

    Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.

    When you share a template, each user can have one of two access levels:

    • Owner: This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
    • User: These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as Make Public (read-only), all users in your Rancher setup have the User access level for the template.

    If you create a template, you automatically become an owner of that template.

    If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the documentation about revising templates.

    There are several ways to share templates:

    • Add users to a new RKE template during template creation
    • Add users to an existing RKE template
    • Make the RKE template public, sharing it with all users in the Rancher setup
    • Share template ownership with users who are trusted to modify the template

    Sharing Templates with Specific Users or Groups​

    To allow users or groups to create clusters using your template, you can give them the basic User access level for the template.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Under RKE1 configuration, click RKE Templates.
    3. Go to the template that you want to share and click the ⋮ > Edit.
    4. In the Share Template section, click on Add Member.
    5. Search in the Name field for the user or group you want to share the template with.
    6. Choose the User access type.
    7. Click Save.

    Result: The user or group can create clusters using the template.

    Sharing Templates with All Users​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE Templates.
    3. Go to the template that you want to share and click the ⋮ > Edit.
    4. Under Share Template, check the box for Make Public (read-only).
    5. Click Save.

    Result: All users in the Rancher setup can create clusters using the template.

    Sharing Ownership of Templates​

    If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.

    In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.

    To give Owner access to a user or group,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Under RKE1 configuration, click RKE Templates.
    3. Go to the RKE template that you want to share and click the ⋮ > Edit.
    4. Under Share Template, click on Add Member and search in the Name field for the user or group you want to share the template with.
    5. In the Access Type field, click Owner.
    6. Click Save.

    Result: The user or group has the Owner access type, and can modify, share, or delete the template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html index 18fbfccbf7e..ceff1b06efd 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html @@ -5,13 +5,13 @@ Applying Templates | Rancher Manager - +
    Version: v2.6

    Applying Templates

    You can create a cluster from an RKE template that you created, or from a template that has been shared with you.

    RKE templates can be applied to new clusters.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Creating a Cluster from an RKE Template​

    To add a cluster hosted by an infrastructure provider using an RKE template, use these steps:

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, click Create and choose the infrastructure provider.
    3. Provide the cluster name and node template details as usual.
    4. To use an RKE template, under the Cluster Options, check the box for Use an existing RKE template and revision.
    5. Choose an RKE template and revision from the dropdown menu.
    6. Optional: You can edit any settings that the RKE template owner marked as Allow User Override when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
    7. Click Create to launch the cluster.

    Updating a Cluster Created with an RKE Template​

    When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.

    • If the setting allows a user override, you can update these settings in the cluster by editing the cluster.
    • If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.

    If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.

    An existing cluster's settings can be saved as an RKE template. In that situation, you can also edit the cluster to update the cluster to a new revision of the template.

    note

    You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Converting an Existing Cluster to Use an RKE Template​

    This section describes how to create an RKE template from an existing cluster.

    RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to use a newer version of the template.

    To convert an existing cluster to use an RKE template,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster that will be converted to use an RKE template. Click ⋮ > Save as RKE Template.
    3. Enter a name for the template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html index 52f2791b7d2..cf3e6bb0255 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html @@ -5,13 +5,13 @@ Template Creator Permissions | Rancher Manager - +
    Version: v2.6

    Template Creator Permissions

    Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.

    For more information on administrator permissions, refer to the documentation on global permissions.

    Giving Users Permission to Create Templates

    Templates can only be created by users who have the global permission Create RKE Templates.

    Administrators have the global permission to create templates, and only administrators can give that permission to other users.

    For information on allowing users to modify existing templates, refer to Sharing Templates.

    Administrators can give users permission to create RKE templates in two ways:

    Allowing a User to Create Templates​

    An administrator can individually grant the role Create RKE Templates to any existing user by following these steps:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Users.
    3. Choose the user you want to edit and click ⋮ > Edit Config.
    4. In the Built-in section, check the box for Create new RKE Cluster Templates role along with any other roles the user should have. You may want to also check the box for Create RKE Template Revisions.
    5. Click Save.

    Result: The user has permission to create RKE templates.

    Allowing New Users to Create Templates by Default​

    Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Go to the role named Create new RKE Cluster Templates and click ⋮ > Edit Config**.
    4. Select the option Yes: Default role for new users.
    5. Click Save.
    6. If you would like new users to also be able to create RKE template revisions, enable that role as default as well.

    Result: Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.

    Revoking Permission to Create Templates​

    Administrators can remove a user's permission to create templates with the following steps. Note: Administrators have full control over all resources regardless of whether fine-grained permissions are selected.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Users.
    3. Choose the user you want to edit permissions for and click ⋮ > Edit Config.
    4. In the Built-in section, un-check the box for Create RKE Templates and Create RKE Template Revisions, if applicable. In this section, you can change the user back to a standard user, or give the user a different set of permissions.
    5. Click Save.

    Result: The user cannot create RKE templates.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html index bcc2c8215e1..b2931bfbf99 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html @@ -5,13 +5,13 @@ Template Enforcement | Rancher Manager - +
    Version: v2.6

    Template Enforcement

    This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.

    By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,

    • Only an administrator has the ability to create clusters without a template.
    • All standard users must use an RKE template to create a new cluster.
    • Standard users cannot create a cluster without using a template.

    Users can only create new templates if the administrator gives them permission.

    After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to upgrade the cluster to a new revision of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the documentation on revising templates.

    Requiring New Clusters to Use an RKE Template​

    You might want to require new clusters to use a template to ensure that any cluster launched by a standard user will use the Kubernetes and/or Rancher settings that are vetted by administrators.

    To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:

    1. Click ☰ > Global Settings.

    2. Go to the cluster-template-enforcement setting. Click ⋮ > Edit Setting.

    3. Set the value to True and click Save.

      Important:

      When the admin sets the cluster-template-enforcement to True, they also need to share the clusterTemplates with users so that users can select one of these templates to create the cluster.

    Result: All clusters provisioned by Rancher must use a template, unless the creator is an administrator.

    Disabling RKE Template Enforcement​

    To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:

    1. Click ☰ > Global Settings.
    2. Go to the cluster-template-enforcement setting. Click ⋮ > Edit Setting.
    3. Set the value to False and click Save.

    Result: When clusters are provisioned by Rancher, they don't need to use a template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html index 0cae607e0be..694ae83217e 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html @@ -5,13 +5,13 @@ Example Scenarios | Rancher Manager - +
    Version: v2.6

    Example Scenarios

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    • Enforcing templates: Administrators might want to enforce one or more template settings for everyone if they want all new Rancher-provisioned clusters to have those settings.
    • Sharing different templates with different users: Administrators might give different templates to basic and advanced users, so that basic users have more restricted options and advanced users have more discretion when creating clusters.
    • Updating template settings: If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, a template can be updated to a new revision and clusters created from the template can upgrade to the new version of the template.
    • Sharing ownership of a template: When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how template ownership can be shared.

    Enforcing a Template Setting for Everyone​

    Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.

    1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as Allow User Override.
    2. The administrator makes the template public.
    3. The administrator turns on template enforcement.

    Results:

    • All Rancher users in the organization have access to the template.
    • All new clusters created by standard users with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them.
    • All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template.

    In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else.

    Templates for Basic and Advanced Users​

    Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want.

    1. First, an administrator turns on RKE template enforcement. This means that every standard user in Rancher will need to use an RKE template when they create a cluster.
    2. The administrator then creates two templates:
    • One template for basic users, with almost every option specified except for access keys
    • One template for advanced users, which has most or all options has Allow User Override turned on
    1. The administrator shares the advanced template with only the advanced users.
    2. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster.

    Result: All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters.

    Updating Templates and Clusters Created with Them​

    Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes.

    In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting.

    The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters:

    • Specify Kubernetes v1.15 on the template: The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster.
    • Allow any Kubernetes version on the template: When creating a template revision, the template owner can also mark the the Kubernetes version as Allow User Override using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes.
    • Allow the latest minor Kubernetes version on the template: The template owner can also create a template revision in which the Kubernetes version is defined as Latest v1.14 (Allows patch version upgrades). This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed.

    Allowing Other Users to Control and Share a Template​

    Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster.

    Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template.

    To share ownership of the template with Bob, Alice adds Bob as an owner of her template.

    The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html index 404ae9beca5..d7a6d7146bb 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html @@ -5,13 +5,13 @@ RKE Templates and Infrastructure | Rancher Manager - +
    Version: v2.6

    RKE Templates and Infrastructure

    In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.

    Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.

    If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.

    Node Templates​

    Node templates are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.

    Terraform​

    Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.

    This section focuses on how to use Terraform with the Rancher 2 Terraform provider, which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.

    Terraform allows you to:

    • Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
    • Leverage catalog apps and multi-cluster apps
    • Codify infrastructure across many platforms, including Rancher and major cloud providers
    • Commit infrastructure-as-code to version control
    • Easily repeat configuration and setup of infrastructure
    • Incorporate infrastructure changes into standard development practices
    • Prevent configuration drift, in which some servers become configured differently than others

    How Does Terraform Work?​

    Terraform is written in files with the extension .tf. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.

    To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with.

    Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.

    When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run terraform apply, the changes would be deployed.

    Tips for Working with Terraform​

    • There are examples of how to provide most aspects of a cluster in the documentation for the Rancher 2 provider.

    • In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver.

    • You can also modify auth in the Terraform provider.

    • You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure.

    • If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use Terraform modules. You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware.

    Tip for Creating CIS Benchmark Compliant Clusters​

    This section describes one way that you can make security and compliance-related config files standard in your clusters.

    When you create a CIS benchmark compliant cluster, you have an encryption config file and an audit log config file.

    Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the kube-api-server.

    Then you would make sure that the kube-api-server flag in your RKE template uses your CIS-compliant config files.

    In this way, you can create flags that comply with the CIS benchmark.

    Resources​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html index eec2c7ef1a1..daa5ca019a1 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html @@ -5,13 +5,13 @@ Creating and Revising RKE Templates | Rancher Manager - +
    Version: v2.6

    Creating and Revising RKE Templates

    This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the Cluster Management view under RKE1 Configuration > RKE Templates.

    Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.

    Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.

    The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.

    Prerequisites​

    You can create RKE templates if you have the Create RKE Templates permission, which can be given by an administrator.

    You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to the documentation on sharing template ownership.

    Creating a Template​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Click RKE1 configuration > Node Templates.
    3. Click Add Template.
    4. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
    5. Optional: Share the template with other users or groups by adding them as members. You can also make the template public to share with everyone in the Rancher setup.
    6. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.

    Result: An RKE template with one revision is configured. You can use this RKE template revision later when you provision a Rancher-launched cluster. After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck Use an existing RKE Template and Revision will be unavailable.

    Updating a Template​

    When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.

    You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can disable it.

    When new template revisions are created, clusters using an older revision of the template are unaffected.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE Templates.
    3. Go to the template that you want to edit and click the ⋮ > Edit.
    4. Edit the required information and click Save.
    5. Optional: You can change the default revision of this template and also change who it is shared with.

    Result: The template is updated. To apply it to a cluster using an older version of the template, refer to the section on upgrading a cluster to use a new revision of a template.

    Deleting a Template​

    When you no longer use an RKE template for any of your clusters, you can delete it.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Click RKE1 configuration > RKE Templates.
    3. Go to the RKE template that you want to delete and click the ⋮ > Delete.
    4. Confirm the deletion.

    Result: The template is deleted.

    Creating a Revision Based on the Default Revision​

    You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE Templates.
    3. Go to the RKE template that you want to clone and click the ⋮ > New Revision from Default.
    4. Complete the rest of the form to create a new revision.

    Result: The RKE template revision is cloned and configured.

    Creating a Revision Based on a Cloned Revision​

    When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Under RKE1 configuration, click RKE Templates.
    3. Go to the template revision you want to clone. Then select ⋮ > Clone Revision.
    4. Complete the rest of the form.

    Result: The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.

    Disabling a Template Revision​

    When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.

    You can disable the revision if it is not being used by any cluster.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE Templates.
    3. Go to the template revision you want to disable. Then select ⋮ > Disable.

    Result: The RKE template revision cannot be used to create a new cluster.

    Re-enabling a Disabled Template Revision​

    If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Under RKE1 configuration, click RKE Templates.
    3. Go to the template revision you want to re-enable. Then select ⋮ > Enable.

    Result: The RKE template revision can be used to create a new cluster.

    Setting a Template Revision as Default​

    When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.

    To set an RKE template revision as default,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE templates.
    3. Go to the RKE template revision that should be default and click the ⋮ > Set as Default.

    Result: The RKE template revision will be used as the default option when clusters are created with the template.

    Deleting a Template Revision​

    You can delete all revisions of a template except for the default revision.

    To permanently delete a revision,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation menu, click RKE1 Configuration > RKE templates.
    3. Go to the RKE template revision that should be deleted and click the ⋮ > Delete.

    Result: The RKE template revision is deleted.

    Upgrading a Cluster to Use a New Template Revision​

    note

    This section assumes that you already have a cluster that has an RKE template applied.

    This section also assumes that you have updated the template that the cluster is using so that a new template revision is available.

    To upgrade a cluster to use a new template revision,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that you want to upgrade and click ⋮ > Edit Config.
    3. In the Cluster Options section, click the dropdown menu for the template revision, then select the new template revision.
    4. Click Save.

    Result: The cluster is upgraded to use the settings defined in the new template revision.

    Exporting a Running Cluster to a New RKE Template and Revision​

    You can save an existing cluster's settings as an RKE template.

    This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to [use a newer version of the template.]

    To convert an existing cluster to use an RKE template,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that will be converted to use an RKE template and ⋮ > Save as RKE Template.
    3. Enter a name for the RKE template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html index 0469eabc108..fa281bdbc2f 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html @@ -5,13 +5,13 @@ Overriding Template Settings | Rancher Manager - +
    Version: v2.6

    Overriding Template Settings

    When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as Allow User Override.

    After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as Allow User Override. However, if the template is updated to a new revision that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster.

    When any parameter is set as Allow User Override on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time.

    The Allow User Override model of the RKE template is useful for situations such as:

    • Administrators know that some settings will need the flexibility to be frequently updated over time
    • End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html index 64a1e4e3178..6c8ba4fcdf7 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html @@ -5,13 +5,13 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.6

    Pod Security Policies

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges).

    If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of Pod <NAME> is forbidden: unable to validate....

    How PSPs Work​

    You can assign PSPs at the cluster or project level.

    PSPs work through inheritance:

    • By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
    • Exception: Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
    • You can override the default PSP by assigning a different PSP directly to the project.

    Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Read more about Pod Security Policies in the Kubernetes documentation.

    Default PSPs​

    Rancher ships with three default Pod Security Policies (PSPs): the restricted-noroot, restricted and unrestricted policies.

    Restricted-NoRoot​

    This policy is based on the Kubernetes example restricted policy. It significantly restricts what types of pods can be deployed to a cluster or project. This policy:

    • Prevents pods from running as a privileged user and prevents escalation of privileges.
    • Validates that server-required security mechanisms are in place, such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.

    Restricted​

    This policy is a relaxed version of the restricted-noroot policy, with almost all the restrictions in place, except for the fact that it allows running containers as a privileged user.

    Unrestricted​

    This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.

    Creating PSPs​

    Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.

    Requirements​

    Rancher can only assign PSPs for clusters that are launched using RKE.

    You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by editing the cluster.

    It is a best practice to set PSP at the cluster level.

    We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.

    Creating PSPs in the Rancher UI​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the left navigation bar, click Pod Security Policies.
    3. Click Add Policy.
    4. Name the policy.
    5. Complete each section of the form. Refer to the Kubernetes documentation for more information on what each policy does.
    6. Click Create.

    Configuration​

    The Kubernetes documentation on PSPs is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/custom-branding.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/custom-branding.html index 36ea40c88a3..59cfeacf2c4 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/custom-branding.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/custom-branding.html @@ -5,13 +5,13 @@ Custom Branding | Rancher Manager - +
    Version: v2.6

    Custom Branding

    Rancher v2.6 introduced the ability to customize Rancher’s branding and navigation links.

    Changing Brand Settings​

    Prerequisite:

    You will need to have at least cluster member permissions.

    To configure the brand settings,

    1. Click ☰ > Global settings.
    2. Click Branding.

    Brand Configuration​

    Private Label Company Name​

    This option replaces “Rancher” with the value you provide in most places. Files that need to have Rancher in the name, such as “rancher-compose.yml”, will not be changed.

    Use a url address to send new "File an Issue" reports instead of sending users to the Github issues page. Optionally show Rancher community support links.

    Upload light and dark logos to replace the Rancher logo in the top-level navigation header.

    Primary Color​

    You can override the primary color used throughout the UI with a custom color of your choice.

    Fixed Banners​

    Display a custom fixed banner in the header, footer, or both.

    In this section, you'll learn how to configure the links in the left navigation bar of the Cluster Dashboard. To get to the cluster dashboard,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want custom navigation links and click Explore.

    It can be useful to add a link for quick access to services installed on a cluster. For example, you could add a link to the Kiali UI for clusters with Istio installed, or you could add a link to the Grafana UI for clusters with Rancher monitoring installed.

    The custom links don't affect who has access to each service.

    Links can be created at the top level and multiple links can be grouped together.

    Prerequisite:

    You will need to have at least cluster member or project member permissions.

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you would like to add custom navigation links and click Explore.

    3. In the top navigation menu, click 🔍 (Resource Search).

    4. Type Nav and click Nav Links.

    5. Click Create from YAML.

    6. The simplest way to create a navigation link is to add these fields:

      name: linkname
      toURL: https://example.com

      For more details on setting up links, including optional fields, see Link Configuration.

    7. Click Create.

    name​

    Display name for the link. Required.

    group​

    Name of a group of links that expands when clicked.

    Optional. If not provided, the link appears standalone.

    Groups are displayed separately from standalone links, as shown below:

    Screenshot of group and standalone link

    iconSrc​

    Icon source in in base64 format.

    Below is an example of the Grafana logo in base64 format:

    data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAgAElEQVR4Aey9d5xkZZn3zb/P+3mffZ9nDcDAzHTuqs49PZEhCBhBJc10nO7pHKbD9PR07p5AWlEEZM2ioph3dXGNqLgCxhVBRIYRmNy5cjqnTlWdqu/7ue5zTk+DiNIsCn4suOacrjrxvq/fle/7PofX+ycDZNT/pIAUaUUmaRBKp8FMQ1L9qL6S4+VYUikIeuBrn+LppiuJNG/BvHYd7HbhbXLBZ/dB8AkwFokCHsAH6Kb8IxTHJIyBHwgDMTBT6h7yWAmb1L3sxyEjfxkYxDDQMa0nWV0vyE2slwZ5JtUO8v5JUhgk0EkRw5TnUg9sgJm03lsezkyTIU0C2VrNJU2WsdtTPVQyAmYU4mGIhDESaULAcSG5RjwJEQ8YsxgEOZoOcSxjvXsyKM8nL24QJ4UmF5TnlL7IWLure/G/3lnn/PVu9SrdaQVApO3/CCAZAYjNSLIVBrD/VMwSnsf4/B38ofWthFu3krhhPZmaLJZuyEY7vJPIV++AwEnImJwJ66qTFcMLSswkGWKkiKqtMIICwB890zL/2lwoHGLYnCIMtMqP3Md5N7mMDRDTBkhKAURAqNBs3TOdspjWERgrmkYuJbQMEPUeKdAEIBrIuSIKEiZ+B0ShADz7W/Tjv8TMLOIjybxcJwNJOUgAkjHQSFoAkedMWn2g7rXKV/9rnfZ3DRCRjgoN0ik2A0nDLgMkbYD3aU7dPcRT7ZfhadmEVldA/IZ1RN6TRahxO8f37CTyxU/B4pySvOlYHNM0sZhQRKgwTRrRWALOZc0lWksoY30n0lPkuMBCPYCcKn/Ic632Iy/ivNvy+4k2EOAamDbJ/rIKFYEhx74AWPIWcpRhv8dyu5mQTEEkmUYTjSsaMBWDiA9mjsF/foWTH76Z33zqEL6jD5IgRkTeR64valfOQQSL6My0Ap/c32qvlNJgq339v8Z5fzcAkcayBKrFkNIBCiDOD/Lj8jG2iZWOwvGHefxQNY+3beHk7grCDS7067JhRwn6dZX4d72L3zVei/6Vz0HYB/EQJINKawRTQXVP+UfYQEjdRphITBlTNIrFqBopIsqcsZnaQYww0iv5yA1XkuJ+eRJREStJvrMFhnO8A5S09ewCDoMkCQUw67KxOMQMCBkpkok4JIIQnYGf3k/s7mlO7N3Fw7VX8J2Ot3Pi/rvBXMLMJKxbx+UR5L4CEJ0IKYUbeV0xAUXDZVSrvZIGeHXPff0DRDGE9PRZPhGec8jhBWcr30uXCWEG4Xf/wW+H38ajXVUcaS7GX+dGvyYX6jeQvL6MZO1lzFx7Mc81XkPyM3eC/xlIz5LJzBIz/bbUtUyKZaksUtPUIS06wzK/LGluM6jwrVg9wkCvECDOe51lE2kL5w2drdU+Ths5bSBbMacsVMtGtKDFug5+5Q00Iw2JFOhhmD0C3/goS6M1HKvfiqfxMo7t3MLv2i7F97nDoJ+BpG45IXLysgYRgIhvJPeRu4QVibZ7LX/+rgDiNLTT58IADjM4rPI8HyXpgYc+yXODF3G0ZyPPtZSxUFeM/9p8MrUVJK4rIX5NMfEdm1jauZ1j7Vfj/exNcPoRSB2HxIICiHI+Hb4U00mYSWkP4RAhHTKiUexggfCEPJDiUOepX/5W3tN5R9m3PpZZJ6bdWbJ+kWPkto51JyaVxbBnpYtcT35XwFDXt8Ee8cJ//wj9X6c40fF2TtZU4qspJV5bidawCU/HxWgfHoTwccuhl4srE0saRnwQwwaIZQKa+BH6B0CcfnvVttIBK8jmFId5zjKEmA+WhJTIkeoYYxY+t5/FtmJ8zeUEWzdypqmM07VFhGpK0W9wYVyXh15dQLxnG/NdF/NE00V4PzgAv/0OLB5RbyWKQD2CML5wV1KMbIlmCSgkapQEkcLCNPJ72mJAsdXl+Vb7cRh+mcnlQvKl0IomUfs2mOT28rwCaiErgiW+hXWOaBSnzRSw4/Mw/wR87zN4xht55vqNzNxQQXj3VoyWzRjX5ZPcWUigrozozU0QeMbSNAnIyA0EcaQRE1N8EPWn0hoSDxSSRnntfl73GkTMAsvXsDnCYZAXMERc2dei2i0HVnWMdpro4etYuv58orUujLatLLZsZKapkqXaYqINRZi7XWQ63ASacwh2lhPtvZwjdVs4M94ETz4M8ajFjI5TLlsJLavwsu0GCA84JpX4uEAAVHBYGHa1H3lVuZaQxXgvAIh86QDFDqu+ECDSIstS3AGWnCdmUnwRjv4Y/XMHON51OSerSwjv2kCqdRta81ZiDZWwqwjq8onWFKIfrIPQs5CIKl/ekJvZDyagFJJbWKFuiQFLePwfJtZq+//PnieNLc64lUuwTYoXMITwZowMgbSu3EIjE8NMiKMdhmd/zlzrRjJ12UQb3IQaKojUbiRUW8VSQynzjQV4mtfjbz6fSNN5hBvXsrjbzXzTZjz1V/Bs0/Xw0A9g7qRy3E3DRzARUJpKni0ZSljpEUkcCEBsQR3BYIEIC2mxw+WBV/dx3v950TP5UshpBxskqURG+cvCjtImwqyyDYZ9pDPiMKfR4hHQY5aJdPIIPPg1jrS/nZndW/E0lRJodBHY5SbYUEq4biOx2goi16+D1iLCO/PwDL0HfvdD5X9JFNwXP+vjyL2UMJDnUs8kRpzkjv4BkNX1/l9wlmiOhHL4RIbaDrA0vs0UwifSMVEkuSWJsyTxRACMIKSi8Nj3WWyphLr16PWFaPVlGDs3ou2swldXpgCy0LoWT+t5RJreqEASaMpRDGLs2E6w+u2c7mkgcM/t8IdHID2PSZAQUaJmSrkAypgXXrClaTIj5kZcRXXiKlH4ygAibXA2Yme3wUqAJDMWWDJgGEmiWgzDFL1hCRcjHkWP+kgaPkgHQUyqIz8l+fHDzLa/i0DdVrTaUmL1LsINBTZIignXVRCpK8W3cx3Jdjehnfl4970bHnsA0rpi/QWxLqUf7SiZ2pd/BBPio0kQQyVO/4LO/hsd8ro2sYQxRPYJSJSZJYwhHSBkWoJUABJRqTLRM0m08KKlPYwgiR99kZOdlRi71pOuKSS90wJIrLqK2M4yZTaEGy0N4ml9M96W89Hqs0lVu0nt2Ii+YztPv8XF8ZZ3EPrkAfj9dyF50gaJhscwEP5U0twGrZlKkEhKwDNkZ7gV27yC7ndUxYtfwkymMZMp5L7KF0pJNj2OmYiR0MMkRWsIoyY8MPsYia/fyZmxGzjdsInAjjKM6nIS1aUKJOH6UgK7LAo2FBPc5WKh9kJiYoJWF7I08G5SP7sfMrryLuZsYCjZJYlFp39EWKhIn4TBVy8gXvyN/2e/fd0DREoY4sqvsEo8lHQSCSV8Z5c8RDJJxAeRUKvmm4FEGDQ/S1+6k2NdG4g1ZWPWFJLZWUZi5wbiOypJXF9GfIcbrT6HYNNaPC0X4G2+AF0BxEVqZ7k6NvRuN96dGzjR+VZOva+LyMNfgOizYrwQJkIkY1qmhcMcSZGccTJmCF0XJ/UVAESuuRytOssY8rWjSGVf12MYsbDKyYh0z4SXyIQWIB60hIU2D7/6FjN37uVo56XMNpQSqXdj1LpIVBdj1JSi1WwgUrtBaQ4xscTc8u7O40z9hYTa3UR2uvD2vpPIA/dBJooXmLOfQwkIx7SS13X6RwIY/wDI2Y77n94TDWKVMCQtP0Q6QRpfJJRsJXyfgWhaoCFaJk5SACKM4ZnlxIemOd2+mWhTnvJB4nUlmDsqMK8vVwDRdxYr0yLSkEekIYfwrhyCjXkqmajVFlvMc0M++k43vh2lnKzfxqmpRrRvfRwWHlPVW7G0D40YyaSBGRVJLV66xSWmZPIV96yyZRQSnIy9JRDkK7m6NIES1CIYMgkykv0W3yvug+giaB7LnDrxK1LfvYeT040cqdvEUm0JdFRhtpbhr84mXF9MuL4crWYjevVG9JoKYhIKbypgsTmH0w3rCLcWkbjBTbD9SrxfuxvSfnyYLDmvpQIXKzSpoFceVJlX/9AgTjP9j2/FsYyRVKQcdWlr4QrHIzQhYUIsbSq7Py2Z8/CC0h4cO8rRw3uZb9mKvstFZJdoixISO8tJ3lCuTKxItUjSYiVNtTqXAotyVBtd6ju91gWNLpI7skheV4BevYHFhks4PnA9S/feQup3D4B+0o7WxIjrYUxdEogWs4j584o+DkCk3kku9YJIlTjikZROUsIGKfEvvJDyg+EB3wkSj3yD2dt7OTnwdk7UbySwq4pE0wYiNYUEavOJNJfiF5OqoVw55HpNOUICEKVBmgo4U7+OsBR2Xu8itvsyFu65GVIegsRUpkN1hiRNRVvY7+3UellZ9FfYBq+oAf/8ya9rE0sAItlZAclLAUTLpIkmJfQoUZoASNLrsV/x9Gg3vqaLSNcWkagtQq8rUY6nxPT9tWXKUQ/WVygJKlJUnFIHMFKSEqvPg+4K0rU5pG7IgdpSkjdUMn/NBmbarmLu1n7MR/4NPE8qkMTQCKSlhtcSnlIoqyTpn++nFz9CACKaUsiWyqI9RD5ICkLyDhF0YmYYQ1+CmJhVi7BwlNPf+zK/PtBGtPsSwlefy+w7z1P+RazrYhYbN3K6upTFunIFDvE35H0jDQVKMKg2qCtV2mWxJksFOHivi2TdxczdNQqJWaKZABKtIxO2KhZsh1we09JuVtWxFaJ/8dd7LXz7ugaINLb4FpZ/YYd5RZ07XJK0SoESaZOY5icj9dcSvZLy7Ie/y+mBBsINW0nXlJKsKVEAEfva11CCTyI0dWUogNRV2FEbkZ6lSoKKjR6pd5FoLMLcVUSqzkXyhgL09+ShS/a9fjvB7qs5PlJP8vufhugzKjEmxp4wsDyiVIorS8PGibP/oowhP4oIdrbOvi2V5VfHtLJyDhLhk5yPbmmN2Ax4j5L61bc58pGDPDTcyFNd78SoLoTq9dBUjL67grn6ck5Ul3GmpgJPQxXB+nLCDW4VwXLMSzG7YrVWW/h2ZqHX5cF1hcTrt+G5bS/EThNP+YjKmwowklEwJWJllZo4Cl4EnHqdF33h18aXr2uAqCa0TQtpaKvCVuobjGVTS3zAuCHJvCCYAZICEM2DcecowV0X2aZDKbo4ohLOFC2xTGJarKA66xjruGIideUqbyI5AUvTyPluxBwzatzqev66TXj73g2fvRWOPQpxj2KaU1qIZ2NhO5ttMbcw+LJ5btsjmYyE44QEHBKIcLZytDU2Q5KOkmqRrELELsBPZOKQDkPKC8YMnPkl+r/fydHhnfy+YRvzjdtJtl+GUVNMosaFVudW7y2ACDRUqPdR4Kh3tKZoEREK8t5WG4mppTfkE63OVu8c7ryMk/vq4fhvVeInYJorhJVIAyvULhUN8p6veXQAr2+ACCrEvLATcAlV8xNUA4WUHo+DRDWTCRnLEADTgxxDeAbz5naSNWXLwBCmf7kkibJw7VYCddvwN2zE21iKv9GlnHkV7arJg8ZKaLmUeP8NxO+cgF9+T4VUpZJ1MR1TCbuzDvXZ6FPaCYvKOzpaQrbCWYoEKOJbpfASZyEVYTERJGRKUFukdRik1mzpaXjk6yzePcLxve9ltmkbkboK0tUlZKrd6LVnGd5h/L90K8IgUZdPpCbb8km6L2W2fycc+ZXKhQTkOaV/RGWIv5XRVd9IxbAChy3cXhu64sWf4u8OIHGkFF23OiYOetQkrQoHxbySMYE6zD5FdLzOju8XK5NJpOHLJqVdJPy5Udnq3sZiPLsL8O7OIdyYrULEyVo3qcbNeOsv4Wjj2zl2yyCZn/4nhE6qkXppCSRImZZpkRPkUmkLqWdaaTeJ8xJNk4mYZMIp0mHNMhkTS6rM3Kpt8oG5CN4j8Mwj+L54JzOHezjW/HbmqrcSq5YQtovUNdkY165Hr7W1ggpGSEDiLycBiFGbpwAigsHTtZ2Z/hvg1z9WWjKsRk39AyAvDr2/xrciXYWBVmiQuCqjtgFiQDRkmSLL5obk1Z98mKW+d2PsLEHCtS8bGDaYRONIIk2rLVcOqwzTXWjJY6ElB//ubKVJQjuyiVaLlN7CfMOlHG27iuMHOkh842Nw9BcQ84IeAc2maBhiMuYiCJEgEm3j2afh6FNw5En4/eOkn3iUzOO/hsd+Bk88BI//CJ78L3juF3Div+G3P8T4z3vwfewQj7VdzTONV6roWrLxIlXGn7khH65bR2ZHNhKJezmgWHmsACReY2kQ365Cljq3MrPnGvjJf6j8SlTU4PM0iDUGRHyjf2iQvyZARHur6Ig4wFGVEFQdk4BYWPS8HCCOokhXP+Eff4XZjiuIVxe9IoCIeZLaKTa85bB7mwqYb81jti1HgUQ0iUR+gtflEb2uGKPhIoJNlzHbdDmefTtI3L4HfnUf/Pwe+OHd8B+3wudGMT7cQ/C23XhursV7Yw3ew9V4DlzP4tS1LIy/h7nRq5nd/w7m9l1FaLgeT88OllquI9xRjdm/G/qbibVdz2LNFczVXsJ8/RYWaivw1rgxGlywuwh25UN1tkoGrmT6l7MvANGr84hU5+JpzGexfSMz3e+Cb34GdC9xGaIrALESMsrekuG/UtHwD4D8DQAiDS9DPsVZd0I6CTFLRJJJNEUAEjnJwlc+yJmWi/4HAOLG3OkiVS0h3wKVPJtvKWCmLQ/Zirnlr8kjurOA5A1ukteXkthZgV5bRbhhM77GSuYb3cwJsHa7WGh2sdTsxtPqwt/qVhRocRNsLiDYlE+gMQ9/Qw6++vV469bhq87FaN5GtHoLwasriF1VBddeDDVXQt1boe5StOrNxHZVqfox784cwrXryezOh0YpmblQDTF+OaBYeawARNuZvwyQhfYK5trfCl+4EyLzmKrU3/ZDRE5lZEShjLBcAZC/Bp+8gnu8/n0Q24GV9heAWMM4ZRyG3TGSaLYdRFI+mP8tpz48ohKEEmmSTrZCti9/K5EfAUequkAlEcUOX2h2M9viZr65GE9TMUvX55KQ7HRtKZnrCkm8NwdzRyHpWpcybxJdm9G6thDr3EqkfSPR1irCzZWEdlcQ3F2Kt86Ft64An02B2gKVxJNEnqIGF776QjUSMlBfonI2oZoygjfIwK9CNfhL8jvplgqSzUWEG7Lw1a5hqfZNeOrWqPCtFcaVUO7LI2m72I48wjtzWGrMYb6tlPnWizE/cRiC4mNJlMQ2g6WfVFhXQs82QETtv8Y/r2+ASOPakRALICKh7LCW9YX6XUq9JcRI0gfHH+H0+9rxNm9RodhXChAJkUrNkoAssEtAUcrC7nI8jRX4d1UQra9QtUzmDS7YUQA78mBnNunq9aTq85h/73pmr8ln/rpCFm9w4a0uIVgrSbhyIg1lBGqKCFbLAC6poC2y/SUr6y8l+r7GXPxt+QQ6ixR5W4tZairEU5uPrzqPeEOxer5kvYtUc5Eqq5mvXcOJujczs+tCAo0FLxsYDpCk7aLXWwBZbMpisa2IxeatpP51BHzPWZM7SD8ICRgUIOz+Wf77tY2Q1z9A7Ia2+kEST45TbneMjHKNZ0gbGsTm4dff4Ll9V+HdVUFkR54aKBWuc7EakkFWMaGaIsK1JWpUnb+uEl99FYHaKjWuRKJGcSlf2VGiRt4ZNdnEa9cRq19DtH6dun+0RiqHy4jWlqhtrKYEi4rUtbWaIixyEa92Ea8pVNtoXT6epizmWtcx15JlUy4Lu3PxNeYTqi8kVluIVmNRTLROg5yTy1xLLvPNuYhzHWhwrYqkzVKitXbmEel2M9ucQ6BlI6cHr4VnfmbNpyUdY/uIFhRWRFVe29hQT/d3ARDBiAMQ9VYKNHZ9kgKIOIoJ0Bbgh59kpu9ygo1lRHfmvyKAWKCywBGqKyNUW6lAEarZpPyC2M5NaIoq0apLFLOG6yVnsA7f7jX4G9cpYMZqyrBIgCH7Jep4BYrqEhscAhKXTWcB4m/MwrN7Hb6mdch+qEEKDHMRMGi1+QpMAhABijyvgMG3y4WnsVCRf5XgkOvI9TKNlerawW4XpxsvVLVbZ/a8Ax7/nnLUpWOk9spRIhZabCH2D4C8+i3gaGoLILYaV2aX3QkSaZTaCylBic3BFw7i6d5MrEkYNl+Vi0id0epIRtcVWyPspCSjbgOxmo3Eajaj79yKXr3ZcpKlTFyNpXCrEvHFlmzm29YiWzlfEncWSb2X7MvWrv1a3p7NaIs5p0LT9S60+jwStdnKbEPqwa4VyoNrC1QBYXqHW5mSco5VmWuFtSUCJyFu+V7GdayG5Fx2b1ZmnL87n5O7zlNaa777Cvjp1yC2ZJm4diBL+mi5ImA5+/nq88grucPrXoM42kPgIPtn292ydSURJ9l09aPvGJHbWwm3lxFvLlYRHLHjpZJ3NRRqLCLYWKK0kfgL4m9odVUqShWv2YReu4loXZUayhtoKsHb7GapJZ+FtlwW2rNYaslV58t50Xo53yJ1rYYSIg0lRO1tZFcRFp191uguqX/KJ1mXT6Y6H3bkg+Q4ri+EGwphhxuzxi7ErC9S1crisCdqyzCry1TwQMbdhxrdqyI5l8aNGLtK8HbmcqrxXPRdBYR6r4AHP2dVDcuQAztXKH1k9Y/s2QLslXDvX+Hcvz+ALKsSVd+gZsuURLoCyPHH8Ey8B6PFhdkiYz0KiO0qItq4Ogo3FRFqKlYUbSwmtqsUvaGUeH05upSIN5QTbiwluLsYX0sRvhYXntYCfK15ioLNecQaXarcXkruHbK+KyDWWIDeKMesoKZcYjbJOJbw7gKCzS517aVWF/PtFkmoWL6X90vWF6mK5UxNMUIpSXDWW88qzx3aXbQqiu0qJlVTqTSIpyub2eY3k2krIrnvbfDtj1rjTaQWzh4DvwwQmfFFjc957YPkdQ0QR3sIJqSplQax2l6VlMiUm6rOT6KKaQj88gGWBq+E1nwyLUVEanPQmtzEmopXRZHdxUR2uxXJdYTijdY21uQm3Owm0FqIt80if2uh+jvcXIjWlE+8KR+tSfbPUmx3IbHd+RYJgGyKNOcRacl5PjXnWfdoKWapvZjZzmJOdbs52eNmpsvNggyFbZH3c5PY5casd5NqKCbRUEx8V4kyM+Udws2rIzFT9etLlgGy0HYedBeT2Xcl+hduBn1WFVeenWLIcRb/AZC/gvKzAOGAYxkgdhRRaq5UqbeNIhFaz/3nF/ANXKoAQoubUHWWYh6HyVezFYYWZtd259lkMXGoNQd/Ww6ejhyWOmWbR6A1TzF+QrLYdYVkJMrU5CYkz/I8soAk4LIoX4Vy/W15rKRQSz7xxmJl4lgMbwFWQCFg9LQXstRhkewLUOU3Aa7zrrK/WlJ+3LVFGA1leLuzWGw/HzpdJHsu4rRUCcwfeXGAqBGVMsJTek0lSP4q/LKam7yGNYg03AtImH0l2X9KM4udq5xASzjZVq8M2LF/MBIcue9u/AOXQ0chtOYS3HkuWnMBEdEmq6Boi4toSwFaS766jlxL9iOt+QTb8vF15CKmh5C3M5tgezZ6cy5mYz7UCxWo84JtBTyfXATank++dhe+9gLObgsIt7owmmQ8SolNRSTFZNttPVegvQBvRwGLXfksdMlWzrfuFWktUM8uzy/7kRbXi9AL26WESMsKai7FU+0i1FaqAOJrPRfackk2l3F85Fr43Q9UTZb0i5hZ0keqS6WPVg7DVUEV6UyJBzsduAI49kzyZ7veCuf/NQD2NweIemm7ASwbyW5FaShFYh8JOWMhbFTY2DH0FKFYnEBaJmawf9OTEI1DPIVKEkpnhDw8dfdBwmPXIqFW/7X/C63h/6J3FBDrKH4F5LbPLUVrq0Br20CsfQORjgrCnaUEu9wEevII9uQQ6c5C78wi1ZYDLXkgJlPTeQR3WxRqXkOweR3B3VmEmnMJiXllP1u0qwShSFcZEdnvLkXvKiXVWUK6vRizrYhUq4u4Ddjobjk/l+DuHIIt2YRa8wi35RNtK0BvdxHvcBPvLCTTX0Zqj7UfFaEhxyvKJbS7AL2t1KZy9LYK9NYNyxTs3MCZvnJO9RcR6F6P2boGGtbArlx8HZt5Yu+74blHIHpazSujy8yWUuErGJCpkJYk9C6DWVIQS9jDcmWAlcxbJgdYCRQVJl4xQbhUTJiq5k7mPZaLvXqfvz1AnBj5WfFgN4wARIAhWmAFQBylImLJljwpE8JpmXTZBoiIKl2mNMkQlepYmazg+GMcOdSJv/cdBGtz0Rr/mVjLG9A684h0Fq+Kwp3FBLtKCXQJEEoJd5YT6Sgn1lFqkwBPAOQm1ulC63Ap5jTaC0i0uZBttD2HyDIJE+cqRhZmDreKlrA0RailUDndgd2FquZLEnzeXXnonUXqurF2l2J+0QYWMCxm1zrc6nfZxtoLcY6LthUSEQ3TkoO3JQtfS5YCUrglj1hrAUabm1R7MYlWtyKjrRi9vRit3Xq3SEcp/p5iTvWXcKbfRbgzF7NlPTQK5aK1lnFqz0Wc/FAXxq+/BimZ4ySKaWhktKQFDBlyvDLEJdEUGXkY91ujEJVQtPIoAgM51NIvUq4SVmR98/cMEOHpleCQ/WU9LA6FTUqb2ClZOcYGhxxtJFLEjJTS2nYLKmUkQzp1meTTnIOf/RvHB65Fb96OUZ2P2VeAv20Nka4CIp3uVZGAwtu9AU9PBd49bvx7cgj3XECs+3z0rgswOrIsBmupING8WRUW6i1b0No2Kk0T7thAcM8lBHovw997Ef6erfh6qvB1leHvKsLfUUi8v1xRYk8ZiT0VJLorMbo2kOisIt6xAb13I9G+DUR6qwjvqSDUU0mop5xgdwXB7jKWWouQ6Ja3vQRfRzGBrnL1e3jPBoL9Vcz3livy9pap4/WOEhKtxdaUq40F0JxHujWHVJul/cI96/H3rmexfy3evvWEOwrR2oqItZURtSncXkKoo4iFnjKe6d3MiffVE/7OR+HMb0Am7ktrpE2ZsClD1ATNnsPMshIMezoima9LhuxafS7yUMAhW+vj8IYwwtH2mK0AACAASURBVKv3+ZtrkBf6FC8KDtU0KxpiBaDiCQMhmR9agUa2KUvaxJUenwf9d6S+cjNL3ZdD6zaodcPQRubb1qsSiWhXEashMXVC3WUEe0oI7ikk2JtFqG8N0T3nE+9eQ7IzC7O1ALO5HHP3ZhK7t6G1bCfcth1/5za8ndsI9V9OsO8tCij+nm0Eujfh79qAv70Uf0cx3uZ8fM35BHbnK5NHImDK92kW/8ClGFGAtJIsX8XyN8I9xaykUHcRDgX2lLDQVcRiVyn+7lJlthldZUpzpFvdpFsKSLflYrZnk+jMQutZR6j3Qnz9F7K0d41633SzG5rE9NpIoHMjiz0bWNhTgWdPsSU0ess51V7BM3vfhudTY/D7H0JK1qAKq8k2ZhI6c8kUkUzGsrClRF40iZhYQmI9KCjZUUpHOFqqxP7y7xkg8m4OwysOFyDI2zsSwop2yOwXzmErtzK6Wf5W/5j2HAEx0FOaWhIMjsLv72Pp5huItGyAzougqRRz31Zm2wsJdYttvzqA6J2FinnS7VkkOnPRugqXr6V1WXZ9ol2kbw6pVrH93Yjd7unaxkzPW5jv2U5kTxnx7gLiXUWWuSQmTGs5sdZKoi2WTyO+jfgClrlUgN6Vi96VTbxrHVrHhWida5ZJNNdKCrW8iXDrm4m0nUus43x1XLz7QoyetaR6sqC3CPaUwZ5i6Cki2eNSzxPtzifcnUeoJ5/Qntw/okhPrvJj2LUBdm0m0bJBaadZ8UkGyjk9UM7inlLlR9FZgtnmxtNejveDTfDYVyEzq2Zc8WCySEZNESTTM1n9qEqwQeYSUHPAyJgFMaDtyQGFPeRPoRVy89WAyd9egyyDwgGGAwirLFqcMGuCaqfe6vlbOdoBiClDVMW3k/GrMsWPcZzQo5/lzGc6ebarglBjIXRuhLYK4n2bWOouI9xTSqy7eFUU73JBe7aiTHuBkrzJ9kqMjg3EOyuJdxUrHyfWlaUcdHHU/T1uPD3lLPRsxttdgdaejdl+gTJhku35JDrcGJ2l6nytu4pY9xYi3VsI7dlCsG8zgf6N+Pduwje4Ed9QFWe6rNzH6Z4SzuwpZqa3jJneEoRRZ/tKWdi7gYW9FcwPVDLXX6a+l9/P7CllsdtNqrecdFcRiY5Com15hNoLCHQVEuotItxfQrC3yNrfU0S0pwi9u0iBOdlZRLqtlExzJWZLFVpHJYEeuUclswMVLPaVEepxk27NgqYLQbY9JSwObufY+xsJPHQvxI+rhT/DagWqJFEzoeYPVh0qnSrLRygUSKeqjrU6X76WiMzfP0DssJ74Fyu0howXsIBhgUN8CecIZyu2qFAsmSSeThNPmWoOWjVBmRGGM0/AL77KsX9t46n9F3O6w0203QWdpdBdTqijhEhvJdGeYtXx0vkvl2KKWYpJdhSTaSuGllKbykm3laN3lePtKWa+z83sgIv5/jy8vVmEe9aS6DxfASO9ex1mSzbptnzMrnxSfS4Sg0XEhyuIjFUxt7eS0/u3cmb87cwcvJ75W1tZ+mA/3rtGmf/INOZ370V/4F7iP7gP44efJ/ngl0j9+IuY//UV0j/5Mvz062qrP/B5fP/xUc588Q6euecmnvzIAf5wRz8nJt/J3P4tnOyt4GRnKTMdxfh6KtH3biWz/2IFVKOjklS79U7yXplWi8SJj3bnEugtZKm3ksU9W/D2bCXSWYnZng9ta6BnHVrdPyEROnPsYkKjb+NY18WEpnfCN2+HM/9F2jyhpmoVq0F8SS1h8b70tQjHsyCRCejsUYoCDvHa/741iAMQx5yytgIQmQjO+k/A8XyAOOCQBtRUOtCad1eNGpRZA71HSXzn4xw9UM+xfVfyXFsZsaHNJPZWqmiS0Vem6qBifWWEbcn4csEhx4v2CfVsINwtGqOcVHupKrVQ5RYSnu0uxttTynxfKbP9xcz3F+DvzVJOvNnxz5jt5xHtKFQOdaC3iuC+LQRGLsY/fQWLN76D2Vuvgf84AN+9HX5yLzz2HXjuUVg6DiEZHSnj1kPWeHZdVqKVCNCfIRn7LueF/OA/BY/+O/z4bmJfmWLu7g5OHtzByeGrmN/7Nvx9VxDu3I7esZVU20YyrZXQWm4JgdZiUh0u5YcsDmSz2F+EV4IEXRXEO0rItOVC6zqMhjcqX0zrkQBBKaHujST7Loaei1jq3U7gK1Okn/0OJGfUNEWJpEnAgGDaWqBKcGCFciWaac/Q6Mx9JoygzIdXw7iyrvk3NrEEIHYo9wU+h0gOAUYsqas1ti2QpNXU/VpcxzBkjiWZORD8yTAZAUZiFk79HP2rt3D64E4W979DRYciPZuI9FQR2VNBuLeEUL+bUH8h4b5CIr1uIr3Fq6JwbxmhgYsI7NtOaGgL4X0VBAeK8PVk42lfy1LzGrQ9Vpg30laI1llEvLcUY28xWl8eS31uToxdzLGb3sviv7ahf3EafvBJ+M234blfw+yzEPFDLAq6zPUlQ4nFiXVyRLIvs+OtklKylqBMYC1zZy2A/1l4+mFS3/8c/k8eYPHWDuZGriW4753oA5eS7tsCPRXQ6YaOPOjMJT5USnS/1F/lYu5dT7L3QrSutfhac5nfXajMQ61rE2ZHBbQXQ1shtBdidhYjkbRj+7ZjfGUcnvsRhE+QNmJqfi9ZWkfm+1KznCnr24CUzOIijrvARozrV//zGgGIo0EsA8oBh4BCZpaV5Q3ipoFuRLEmfLYYJGnGmUv41YqzSgL9/rtEPjPK7ORVeIYuITl2GWLHG50Wad0bCPWV4B9w49+bq8gCyWoBUkJo72Z8e7fgFZ9gpJLAeAWBURf+gWx8XRdi9rthsBIGt2Ds3YZv8BIWxt6B933VLH1sD8YPP0ryv78Gxx4C/x9AZlrXRDNEIBg5G/wXv1XW+FieVtQywxWLCAOthjIQ0ZJoyYwValeTLAgYF8H3DMz9Gn79NTJfO8zcjdfybO9G5nsr0PZvwhypwtxXQbK3HGOPi8SeCzH6ziW+91wi+9bhHShmsbeKQM+laB1vISPRw5YKCyAdORh7soj05ZIa2Yxn5C2EPjEIR36gZoGUyR7mE7AohpcpARd5P5lXQISpRjIZQktbK7682lOXvgYAskIa2supiea0oCLbNEY6QVQLocl0OCr0JwkliWzEVJ4jkzoGj99P7GNDLAxchlcy2AMlxPaVou8pJdlVCe0bSXdUofWWEtjrYnF/LovD2QT3uoj2Fa2aRFJG9pSgDVcR2l+JZ28xnoECtJEiOLABvS9XZdElJzAz9nY8HxtSfgKnnrKWbwuKiSTTg9raQGL/GV2tgmUtj+CYmxZWBCDin0oCWvalrVb7EQmsEttSki5zc6mtRAXl6iLDpdjwGOiPw6lvk3j4Q8x+dg9P3nw1j49cwrHeKlLid7WXkt5bTniomDP7cjk5uJ6FoXxi+ysxujeT7LiEZNtbSXRcjtazmUi/i+DQm4kOvgm616vk5cz+K1n8zCippx8EM6T632OkCMQzhGPidwhARAoY6EkfYdOrVl5XczKvtgH+gvP+tgBRkQp7PT+pwzkbrX0+QJKamhldqVgjjBlcsObXTcv6GsfxPPYFTt3ejm/gbZh9WzD7iwkN5OIbyEbrc5HsLoH2ckWJnlIFioXhXIReKUCMgVJCnYUsteYQ6HRhDFVhjm9BG97AQn8R0ZveQuTO64l/aQR+/jmYewIkiGAzpRIEUhKehFjcJBo3iCY04qZGAs2eBURmApGAhQWI/8mtU8Yhgb9oKkM4lSSc0YgisSUfCRaAU8AxQDTcb0g8803+8O338+Rd7cr8MnsvJdS3nfl+GW5bxtxgEYGhIuJD5eji8HdvJdJzGYHeS/AObMSzz4V3+M1E972BVOMboK8cfeRijo69g2c/PUbm2YfU9EwChlQiSTQSJ67ZdXWyTHVGpuQOqxls/r5LTQQgCiRnnS0l1VZoEGEGNQuGWndcJK3M0O6B6DzEjhH41Sc59slWZgcuJdWzFfZUoHVmsbh3HeEDLqKDOaR686FD7GY3qT3FRAfceIfcLO13E9orf6+OIgOl+PaUEeqtwOgpJdNdCj3lsHczxtTb8PzLTvj5p+H4g5A4LXljtU6JP5ViMawzGwgRNDQFCN1MIsuzyfuKNWGaGSsq5xTwKfPCWbZM5hqWBXGseiWnGVe3XVn45wRJ4qRFi2WiJNJBYkkfkZRHMWWcKBphvJlFwv6nmP/mR/D+6xBnRq9lrutSol2byfRvxezfRKyvAt9gBYv7y5gbKWVuxM3ScD6+/XmE9uUR788j05YNXW6SQ5vxT17Oczdew4l79pF54n5IzEBKSoV04ppOMmXlwtIk1eJ7ii9e5TDW316DOAARBWIXLQqTiGRVklJpFjHD7BIEWedCZicJncH87bd47Jb3MDu+lVTfRugsJ9GWh6f9As4MrcN/MJ/ovrWk+9ZCVxZ05ZDszVcACQ6KJikj8goBstTlVgDR+qvQ+jajD10Od7TC9z8Kz8oquIvq2WViackfz6QzLKUFKhLUzBCKB4kmIyQyoiXOJkOV7y02j+NbSORGrbEh64s4AJGrnHVWpSkdLfyXbOXiGbWIj5irTjLOWqJN1i6MabJMnMwSLzPoy8TYsGgmmU0nmFeGWIq0/wQceRi+fQ/6HYOE915NqGWLKtgUcza4rxDvcBaLYxewNHoBvuF1BPflERkoUwCS+jTJvxgD5SQnt7M0spWjo5exdO8gPHW/NfF2Okg6k0A3TeIpazHSjCwrZ8gqodY7v1r//u0B4jDACwCiwCHS1JnNXCIYRggML/hP4v31jzh272HmhreSEQ3R6YIOF+E9LuYHCzgxms2Z4QuI71sD/edC77nQvwZtMJfwYAnC0JIs1KSj9hatirS9LpjcgD5UxPzQJvx3NsGDn4b5p8CIKZQLvrUURAzQhcdVT6ZVLZKmiZ0vDJ5W852bmRSptEhHK/n5ohpBhIhNZ5ljZSO+jH2ZyC0WISMr28rAfclkv4gfGE0k8IdlASA7ky2HxSGyFLAEl0j5yAI8+RDpL91B+OYmYvsvJj3ottp+4J/IDP4TqcE3EB9cp9o6vHeTigDOdJYQGChH31tKRLL2XbkEhysJvO89nP54Jzz9HYgdVwBWII2nSciO4DlqC5BXCx0yu7u8qwVCJyehQgbqO8dRtjpVDnT8BZHo9okrStXVdV7498t+eOlgub5M/iYmlTT+HERmQJ8Bz+8JPvh5fvPhcZ44cAPcciUMCkByoN+NNlLG3LCL40NZzA+vUwDJDJyLUHLvGqL7cgnvKyLeV0Wytwqjv4j4gMvqtMESooNFimKDLrS9BcQHLBIQRQdLCA+WEdpnkX9ISr3LiN1VAz+5C+Z+CvE5VWQnTq/Id6nkliWRRQEobSDOpvRwRhxhXUlwicwlUjpGUkNPxRFzSyI5MuRLcmEOOf3hbJf7ZYXHptruL/1bhI+Ej6XUPGaQihsqfK4nU8iiQ/KEihclepZIk1RIF7SnIJqBeFqZPoYCV8oSCoFZePS7ZD49RnjyCuJ788kMnAf9b1JgSQ2st9p7oJLA3q3M79uOZ/92fH3l+NrWo7WdR2ZvLsbERmYPvgX/v43CyR9BJqiESzSWsCbhcBpFAdriWcWTTjvL1uFRtSti56yGtnj+zzPnOdIIEuZLRHzWRMpGkIweJRQHX8Jad0KTq0lvSLw9IYVkMjm0tVCNDGlVK4DZW8GQREaU8ycxBzt8n5Sl+WxGERvbuaSEcWUFc7VMmJQTqHU8vJCYA/0EBJ6EmZ/CE1+HH3yI1OeG8XygnpMT7+TkwEai+0tIDuaTHCwkPlRIdL+L0IiL4GghoZF8tOFc4vuzFen7c4kOW8doQyUqY53oySLZl4e+v5zo+EZi4xuIjZYQGxJgZMFQLum9uUT6i1jqK2F+oJyF4U0EDmxn7rZrmPv6nYR++6AFYDH/TA0jFkXTk6TsUv5lIbTcYbYQULkfQ6U6rVUUrVYQplT9smIrESvhCetazvmy1LSMo7BzI85WKjdtyiSd1W1F4NjHiaZQJHMi2ReWrf2gspF7Oc8hW/lbfSQULLNgJERD6giYxPSSY6TfVWjNG4Hjz8ETD+O9o5fZ4Svw7CmFsUoV2ZP2jPesx9hfgXffpfgmrsI79lY8feWkutfAwAUwlEVsbw6nRyvQ75+CpafsnE8aM2pYkb+krpZ6ULP5y4vI/QUrK7MG0lRKP69MPC+/qv1Sf3pzjrycNL6KMZuy4IosmSXrOFg2pyzMIq6gxdEyCCmo1vjLxCIktJgFBFuxpFMmYhsSF3tCA01UtzSmbkkXZxZzZ/bymAf96E+JHvkRoce/jf8XX2PpwXtY+vYdeP79MIEvj3Lqrnrmb78e7/veReCmywkf2kZ0spLoWCmx0SKL4YXpV0H6UCHJvhxM0RLDZUTHNxCcqCI4WkpoqIDI3vUw7ibRn6Wknj6xhfmRbfxh/3ZCH2uFR7+szD1JWjqfRCJBLBZD0zQljZ3vX3wrvWnZ/zJ+XiJVKxnTAYnDoMK4Vu/rloMumeWUQSadIiMqSqSVSB9RVbL5c1slzUTQ2bafLXUdPpNnEZKntLFjD2Kzw+xqQRxL0zjaRiaxFPmZ8SVhdhGO/Abzm59k7uYmTvZvwz9YRmaiBEbzVHLRN1BFYPhyAiOXEhnaBMMlMFkEY9kk+y9Q/ey9/Rq0733YWutEVqtKGKTj0ioy1WzMjmbZAHEALw8u+zZABB4yq7z4U897nxfvmOVvzxEAyMupj7Lzg6QTIaJxHa9usBCPs2RohBMBjKQPM+0V11I9WIogaWbI8BzwDKSPgnEEor+DwOPgeRROPgJP/wh+9Z8gSwR/+cNkPn4Lidsnid/aS+TA9cSm30ls+h1Ep68gOnUZkaltxKY2E5ssJzRWQHgsh/D4WiJj5xMZfxORsf9DZOz/IzL6RqIj2asChwBK2+9SmeDEUBnJkSLi48X4xzewOFbJ4nAxS4NuVQ+VGK2AkQLM0VICt1xF9L4x+O13rYnolJMr89IliMfjpFIpMlK6ncmofadpX3wrjCzhSyHLbBXmdCT4SuZUHa0Uhy3BJR8kmfCMwMoKdr7YViw6iY4JU8jvcm2HrCSb46BLyMAyQZbVuxxonWidZONOvhKRICR5KusJFCdawJRdeXjh4XgKluYxHrqfUx8Z4pnxK5kbLCYxlAWj64n2riXen0+mJ59kr5vwyDYiBy4iPOrC07de8cLMyEV4b3sP/PgOCB612wuloSWJLIsiSTDheRpkBQqsuj4Bk5AVKZRXUzLkxTtm+dtzfAYE4qBpcUjIEgGiQXyoiZ5lXTtZjEXq95NnVHUskT9A6Aj4nwLvf5M59XUyz34W44kPE3zkfSx8e5JTX+jj+CdaOHlXPSduuZaZm65h6dA1BKbeTXT83ehjV5EYfhfsv4K0lB60rrOofS10rCXTfSFmz/kkxLEeW09mYh2pqTUkp8/DOPBm9ANvInbwjcQOnE90NIfYiGt1NOzGGKtSlBgrQRsrwj9RwcJ4BXOj5cwNl+Ef30RkfBOJySrSH7gavvMvajkzlctIWhJbgBGJRBRAlltWBJiYpC/1UWgQ6b1CggtzvZBWMqpjPigT12JKh4dfbCsOdixpoKVSyq8xMk4pqMXcsqSoQUwZuSJd5Vbq/nIxYXKH5L5iItt8L5aHkPxsiWo7BJ0W/8qW5vJ4coK0kyyc+uzPCX39Vv5w8F0cE59utABz34UwKIGUtUqTL+zfyqmxS5gbrWRufwmBqYsIT28jNl1B5K6rMR7+FETFz4OIWPzqGawckWJ4555yXxsBFkAERJJ0PeuHOL+/VBedE08lEScrbUSs9fOiJyzJ/8y34NHPwoN3wPdvg/tvIfXlQ0TvGWPpQwPMvL+ThVvqWRi9FN/wJvwjm/GNbVQMFZjYiH9qE/6pjYQObyZwuArfwUoWD5QyN1nEmYkCTo/msTCUA6NlsK8Y9hXBYBH0F5Lqz1cx8uhArpLy0RE3oVE3ofEiAlPF+KdL8B8sJ3SgVEmaVwKQ1HgF8fEqgpOb8E5swDfhxjPhZmZqA3OTGwlOVOKd3Er0I+3w8/vAd8Raa1ySe7bzqurCEgkr4ma3tmiUaFTc9D/zkU50ACGdqrhcfAMxfSSDbPsJDvfLMSIsbV9PggGJjJVDEfloaRFHq5hKeyjZmZHsQep5f8tKHWFSyh6I2KFcuc3zJPELASIxhhf4RkozpXTSMlow4YOMU0Wlq+XvTPFX0mIO+sHzFNGHP8cfPt7PsQNXkh7Khv1vhulcMjeWEzq4lYWJS5mfuBzPgSuUsIrfUoV5sBD/SCGhuxvgN99S682L5SPPIs8szaIwYfu/0qwWCXjEz3PIEir2j3+mc+Ac9VKiNdIRCBwn9N9f59i9+znz/muIve8KEoc2Yx7YTHzqEiITbyE49jb8I1cSGroMfe8WGK6CoVIYKoEhqTsqJL0vj8S+XLShLEJDa/HvX4t/bC2+qfV4D67Hd2M2gZtzid5UQGK8EEaKyIyWYI6VKDMmNVZOcqxSRTK00SoiYxsJj2wiNLoF/8hWvCNb8I5sVcCMjJagjbpXTfGxMiLj5XgnqlicLMc/6cY37cJ7eAPew1uZP7Ad874BePJ7EJoDQypKlz0Ba3KOdFqZVIq3bPPKMbNeqgfOduJyb2LNdCdOthTnOSTOtQUMcYSFKcR6ERNHysPjCYmAxe0QsZSKOBGbF9864WQtIwCxAjGOLyq3UcyzUhLb9xZQOiFm59klEKFAmohjGCFMQxYp8trl60FSpoDFHs8hyU0zCAkv0T/8kvl/uw3/eBXpobXo0wXoN1eg37gR7/gmTo9eyszEJSyNFhCbyiE5uZ7wcA7+qYuJfX4M89nHl4fjOs8ijynkyBILOKI1rECI1WK2KeYIJTn5JT7npPynSIdnIBmA8Ck8D3+e37x/J8+OFmMeLoDRN8LIG0mOZhMdLyI0uYHQpER7yjAmpPAvm8DeLCKDOWj78zFGXSQnXKQni8hMuUmM5dqUTWIsG2M0i8ToOoyRtcRG1xM56CZ4qJjAwRKC08X4J4vwjxcTGCkjMFKhIkcS3ZDx0+GBzeiD2zGGLiO1/0qSIxersG5srJDVUGSsSDnkgZES/KMFeMfy8EwXEjjsJnmzm+htF6F9dRKe+xnEJaMLft3qbmlXMyVh2hSmaSpSOZuXaOwX/mR1rGPDixx27CdhfWdfutkyfWTPAYcDEHVN5b+IDyN5ColWSeTKIJOMk9AiJPUoqXjMmjBBQrLyezqpQC3Xs3wJxyKRu8i9rXs6v8tWgUcBR7SaDV47IJYwIW5CTGaXkSy8MsAkT7IEyNqQHtLxBTJSjStMLNp39jm0f59Ev+sqZqc3sTRRijblUn6nRK/OjJah7V9LYug8jLE8olOleCY3MHvr1cS+eYe1arDSThaopT3l6eV9HLJmQHkBQBzwy/bPAURlZePyItKwUcK/e4AnPtzOsclyuNUF+/8X7P9/SIydS2wyj/DBUsKHK4gfLiFxuJTgeAH+cReBCTehCTeRiSKi4y70CTfx8UIFltR4AamxfMyRPFJDOST3ZZMaXI+2fz3esRwWpnJZmipQzOmbLiI4XUJ0qhxtagPahPgIm0iObiY1shVz+CIYvkRRemSbKgpcDTjknPC4G+9IMZ4RFwHJ8I5egH86i9BNbqLv38T83deC/7dqzUDhKbF5fRlL4lpdIZ2dUqaVOOcrASKgEd/kpT/SQ1bnOSsvWdEWcTytDLbjBJ/VWfYKthkJKftAPw3h58D3NMz9Fk78itQfHiH++x8TfeKHJJ9+CPOZn6rv1e/+oxA7AfHTYMxb0UUpo3cYXkwhO6sugBVj7awTLuFKu6hSwsiqzN72n+xKY9FEEviRtXZ1Ff4JQnqRdPy0BZC0rFNoB4bk9aNPwX99kOMf2MGxye0EDlWg31RM+MZStEMu0vvXwPCFpCbdyg9ZHC9jZnIz0Q/VkfrG+6wlLdSzW0EOAbGAYzmqpt7BgYsEQ+zkohz4lwBE5a1slS0Pju7H+8h9PHf7e5mfKCA2/Ab0oX8iPHIBwSkXnuly5ibK8E+Xod20geBUGcGpCkWhyQqEIpNliqITJQjFbNLHixGSaJFFbvSJfPTJvGWKT+SzTOOFygQTMywxJtrITVJotFiR/C1AjE0Wroqik26lrbxKjWeRPHgh8Yl/JvIvJfDgYdCetMpaZGJ4ex1ykaSW0HEkvLTyS38EPLpujWER08v5SA4jri2RSPqUByDgEEhJ5wqjiQcTjmtkpP5MCjNTpyH0Gzj2Tfjlx0g/cCOBTzQS/WgN4bt34L/rOjwfeA/zt13F7C3v4Mwtb+fY9GWcOHwFc7e+E9+d16J9tJbUZ3bDfR3w5X2qnJ2nH4KFp60aNwmjSoLWtH3S9JI1mMk4qRK1GVl70IgSNNJEpTRAluU1ksrmk5GAQUAMLClVl9IaaTe1aKdjZknEzp6pRDGoVEZEn4Hf34/vi8OceP+78N6yidShtaT2/2+Sg2/CHF5HeiKPuPieN27Ff+M2jOkNykcJf+cTVhY/EcaMSvGqNf3TYjyCpoSM5YNYsEla95YucwDidMaf2J4jLyDk5DvEZDCO/YLFL45wfHoL4YlczIn1JCfy0cZF/ZUpM0tCsGJmCRhCU2VEJmxgONtlkJQRnRCywLJyG5sQoLjPgmA8n4RNFkjyiE+cBY/Yos+jyTxik/kvCQ5R2S9F/uFcQuM5hCbWEphah3nXBnigD05/H+ILymwRwSFttBwOtxX4yymWE5CIMy+RLdEulo8i/kJSMVw4GkI3pHpXACg9KEwXAP8JMid+jv6rL+K7/zBzn2rm1O3v5PTN21g4UI55axXcVAaHy0kdLCI5VUR8sgB9rIDYmGSkXepv0ebaeN7y97GRPPxjpfhueQ/zd7TgvWeU2P13wi++Bsd/CsGnWewSOQAAIABJREFUrahl4jikjoM5Axlh+6gan+PLZPALMGI6BMOkQgaiMB1eEpDMZ2TuEqvd5L2U1lUmoJPIdELWsrLvKTVoau7rh/j9wUtYGvg/MPZPcFMuifG1aENr0MfzCB3cRHi6HCZySB7exKm7u+Hx74MmGnEJUrIMuEwimCaUljCEFbZQ7SlWkoDT0RxnZdWfgAeoRKG8lLyIkPrI6Lxf3Mfs+68ndnAzTBXDaCEM5sCgC0bKYX8pZl8+KQmPThYRn7C22qSzLVLfy29/mkrQJsrRJiptKle5j9hkKdHpEsIHilRFbuigi9DBAgKH8vEfzrUpm8ChXGLTBS8JgJcChzBScjKb6NhavBPZ+O66nPSDN8HSTyB5gozhU1BQhpI0pmpQm3ntBJ/V2k7D/fFWolkCCgGIbJ19OVKYRq4dk7XSRTWpS8cgeAaO/hfmw/eyeO8w3o8147ntXSxOb2RJqgRGckiM55GeyleCy5i0BIs+nqtsdW0sh/hoLrLlcCncWAIHizEPujGnXDjHByeLmb3xLZw4fCUz0xfhnd6Cfsul8OHr4EsD8K33wZmfQeiYmi5GTC0pwg8SJYIMWJIKWystYbstjnqVOfsIJayRJSJYxMhRIJE2VOZZ1Brbk05jZsScFDEUJn3mlyx8dRrPwU1oI2tI35hN4uA64pNr0cfFhy0iNV4E09nKxD86fSVz98mIxAdAgVnK8wXESfyGGHp2vylgiI8mZDvqf9xdf/TNOVa1pl37lcpYGVnJpi88hv6Nmwh94N1KnaWH1sPgBTAsodkC2F+golWm+Bc2JScKEDImz5IwoZA2ZZEw9DJNFdmAqLSy41PlyvcIT5cSXgGQ8IECwgfzCR3KJXQo26b1hA9m/1mA6NNu/hQZ0wVwcxHBiRw8H3gLPHirFeJOLZJJBkiZcdWxwruKeUX6qQiRdKZjqyvD9I8a1vlC8iOiORz/RLYCFkVSniP952BOxpk/8wsSD3wC/z19LP3L1fimNiFCJzNZCFP5MJUH03lwoAAOFpAczyE+kWMx/VQeyelCktP5pA64SB0oIDFVsPy3hErTh4rIHHYr0Ji3lBG4uRLfjeVEDxRgjGeTHlkLYtIe2IL/pqsI3TuM/zsfRzvykLUwJ34y+EixoMaLCOOr9hHGl3yORN5kdsSkTsaQ3IP1+/OOU+UqkuiU8K+pJsEU40hpaIl0Lf0GfvAvRD70LuZG1pO8OZ/MbRXKWtCGs2HKBYfEesjDe/PFPHvL1YTvPwCen4J5EtIe9ERImaeqH6R9paHl+eTeapIQK8Ln9NOf2p6jXkYShAkdMx5VJM46yVk48QCeL/Vx5raLmBk+j8jUGzBvXoN2+Hy8h9YSuTGflHTYuE0TeTCRp+xFczJP/SYdJIwoYTztQAGxgxZFDhUgFDvgPksHC9EOCBWgH8jDmM4jMZ1DaipLkTm1HqH01FpF5lSWurZ1jnPu87f6QRcvRfFDbvzvu4zQNw/D4qNKikXSCbwJqYsS7rWljlOEqVryLwfICxteTCtHm6hybcl1BL2YR39J8PufZunTQyze9l6CUxswhBluzIcDa2HiPBg9F/avIbN/HYmRXKUlBBzxqWzVVsmDeaQOFZK+sZDMTUVkbnKp743pHLWV4+JTuep4fVLOuwB97P8lMfW/SRw4n8RNBRg3V2Hcsp34TZeh3XQ5wUOXMX/wck697z0sfWEvyUfvBd8vgTNqftyQDNu1eU/5LhLmjS9ZVdcyMExK9O2aNAGSEgiqUSypEIj6kJiXaFJxaSxTSIYzHIHffZngnVeRvHUzocMb8U4XEz6YS+qmfNKHRBMWwPu3MH9oI8++/53Ef/JBMJ6EzDwyGjMptWdyTUGpyDYFEvlHqgYkAGFVD7ywj1b+fQ4pAYc4ZGEy8TAyDkBFtERCmrPEfvkZTt1Ty7ED2YRuPI/UbRcQuvHNzNy4Dv9tJYqRxYESElA4JMBJKHo+QFaCRMAifys6mId2MG8ZGNKpFjhyMCdzSCvKgoksGLdIvhPwvRRA/n/e3gO6ruu689b62swksS1ZYhFI9F4JgBSpFpdxquM4TuI4zngmseOZzKRMkkkmK7YlkUTvAEH0QoIA2FQs23KXYjuO4xa5SLIkq8vsRH29l9+3/vvcB0KyLUfkzGCtg/vKfe/du/f+73b22UcA+GlD2biLLXcQvffvXNOAxJLNtCrQlEYT482tMq2z4T14BJZ2FISMq5tp+hMfK+4QMF7xlwzAc18i8+URLs7+Oc93/ibnD9yB/0CTaX8+tgP+7kb4nze4499tJfP3BaQ+VkHi7hpi+2sJfqyUwN2FBO8uIbS/mMiBcqItZUQPVhBrLScukLRVEGuptOc65t6PHyyEljeTPfgm4i03E2wpZf1gLWsHGlm/R9a8nszBRuJ3KdOnJQT1vNT5qyyf+Esy/zIHF75pzTKcKlHZiwJ8zXOsQUxLE/TcZZfMs/KsiYDiwJIhkgkSS0eJe3OiTq8nHG3TF+HRY8RnPsgLd+3j/D2NRLtqibeVEd9fDa31cLDMUvLP3r2Lp0beR+KJU5A556JGscbhwf2gQKLrsdIUxSeql35t/l1nlWWZhMuZJxLmOMjUKS4x5q/8kMgX+swFibdUQlsJyXuKWLm7hrXWZvwHawgdrLQROVCJRnT/lRG7pwo3aoypYuyVUUXi7ioS98ikv2rodRubz68jcXcdybvcMCG5p+Y1LUT8YA0/bSy338nlEx+DJ78IMZXSLBGO+S17pOktBZqiw4YLYb6ry17JZ47napdeIfU//kRxh4oXFY/oT2BZWVkh9NSXiB95L/RWE7pnB/67dhBuKSPRXUeso45AazXLd5Wwur+SYGsdkY5dxDp2EWmrJXSgytzOtf1lFospPlNMpqPvYBm+gxV2zL2v5/6WcgKtVQTbKgm11xDqrGWltYLltjKbvF1rKcR/sIDAgZ2EDuwkcqCQ5b/dRuxAFfTshZ7biO/fbe5w4uBt+A69h8Sj04TOPALhZ7117EpbuwIAzY3YxKJueqOCO7cAK2OrK6XJ1YQhHlGdX2xjnkeTj6aok0skHr2XlZkPstZ1p5tMPFhF9GA1mdZy+Nib4WAeq+31fL/jLTx2/G8Jq/5PYLVCtE0+3gZABA7FKWGviu3HeZZ75Tp/yN1QOu1KTsRCmbt1FeXqiUozH/88q0f+C6udd5Bsryd9sIrwXXVu7uNgDb7WSnwtVfhaagwwAk3wYJUxUYCJSfhfIfB1JO5qMGF/NUB07mZQRQWAe2Sp6ojsbyB6T8OmY50BUlozdLDcgdPOd6DRb4dbq4m0ViNwJw6WE28pJ9xaZ77rM92/R+Kxh12aUKXqcR/B0DqBVNqyesvqGu/R44olcbZapDFxlzR4SsjccM+i67H9STCSKbLWmCFmWRbOP84LDx/l8dEPsL5/O9x1HRz4t2Rb30yybQfR9lLCHbUEOxpZ72hmtXMPa+1NJgTrrVWst5ThaynCBLqjkvWOatbaq/C1ubHeVk5uBDqr0PB3VNr7662VaKy1CBiVnG2t5XxHLcudVQS7y4h17iTevo1YyxYi+7eSaCsmcHc+vr8vspQ8B13GjL8vx/+3pTx5cB/Pz3+I0LcnYPnrNuchDS3ayL5KX28EyoYT5ZVkc1RZmySuiT4VXmqZg601d+ltNbSOJNLus5EL8J1jrE7+By7cs4fQQSmJeoKysAe2kr3rBuhvYqnnTr7R8hYufL7TpY7Da+4idCGObRvunmZpsqb+XmXVc3zzjtcJDLoZVw9qmXd3aznG68sTARKPf5zHR97PSx23EOtugP0lcFcByZYqp9F0we27CHgj2F5PpK3GzHuypYy0xsEKktLoLbtsDiXS2kS8tda5AXIFNkYN8dYfH5pA0vkbx7Yqou3FRDoKCXYWE2qvInGwieSBZvt8qKOCpdZSIr01JNuLyLTuINmxgzP3lPPs4T8h/O0vuDb7tt5bvrKIdWXWWs82GGwEExLcMACozGI15NJQXgmIKKg158FU0vbCSMdyRVspiKzC9+7n8tQfcv5gFYGOmwn2bCXYcxOhru1EOgWOYosFRKf0gVrSB+pJHqwl0eJoGekoJtSZT7B7B76efNa7K1jvqmG9qwrfxqgg0PmTxuZzquwzq91VrHZX4OsuJdhVSLRjB4n2PJLteaTbdpBsyzeQyE1ztN9FtKXZSkKiLU1mXaQYz/XcwYXjf0zyiaOQesqcVFkE0UmeZUpC5imSZEa9zlQR7pSznaS5l2zcQCWrLbmU6Pm1nkWPkkvw1KcIHvvPLB/cQ/hgLQw1EW8vhJ5yaKm1xESwpZhLfXtIffEeiDwJkRDZtRgRrb7wem35jLFayeb3MiSvQsWmp7ZgShdyBSBrriGARfwuKWGB1vJTXPiHQzw19E4utdVDWxns30HmYKkJtsy+QCGA+Dp2EeioNYGNtpcZgdMtpQgoidYqoq31hFqbCbU1GbiiEvSrGe1lRDrzCXXtINBVTLCjinjLKwHi76/h/P6bCR7YQranEH9bHi9338rlz47DyiWX1dhEkNf1UAwPu10qxcdg0jWyE4OV4wqq4Zssh+q3tCXyN+9nfeqP8Xc2Q+cW6L/BgLHeU4yvu5hgZymR9jKibRUOJC1VZq1NsYh2baXEPYUQ6nRKQdbB11lLoKPGhmggxaDvsdFRahZJVkm8yA29F+oo2wBSsLOMiM7tKCTRnm/AEDiSbYXud9sqTOFJCfram1lv32v8o10ZpUJz5852N/PS7Hu4/PB+ki9/BmIvuSJFT6/YOvtE1lZPJtTAIhs0bFyxzq4qV+DQkECvqdOKiCsARV6C7x8jevQPWWm5Bd+BagLt5QQPFpFRVq+1Cva/mfWPXk94+l3wvWMQugShhLUz1QLnFa30FGpl1mJa3++h9qcwfsOC2Ps2kSJz57Wdt2rVlNXykF6Di9/g/MJf8lLb7SQ6a6GlwPLUsg7S/rIYwXYxS2C5ApB4WymJVoHDnScLIOsRad1FtK3m6sBh1qPMNJ40b7CjglC7rEu95celcQW61FA9F+/eynrrVoLdJbzcUs3K/B/Dy/9sltHSfj+FOP+ql0XfpDCgYj0tNHMzuaYBVfekVObqM2T+aZqzh3+f8wf3EO+phwFljPJItlQ469DqrlfCHegsM42+3l1qR1+XE2RZSCmieIvucZdZy2irrPEuu29peN23rLpAJeXFwWJQMH5AI3/T2GHvyVLLXdH3ihfio7JZOX4Zz9pUSLiZv/WeEqwnoc8drLCM5lJrOc8dqOCp7lu5cOrPiH57DvzPeVbatTbS3jnmlJAgquSQVUCahnbk1ky7uWAu/ltVWbspa7li6mTztLlbvpk/4kd3NxHpamTlYzutRCjTWQWtO4jdvZPVrn28NPZBOPeoldEIDz6to1e1SQ4gWuJqrsBP5/R1uhxZHPsTsy01JofNXWhErT9jEYfg+EUyXz/GhfEPsNzZRORgMdnWEmgpIdVWRqK9nGhHtfnPCgDDHdVEOyqJdZSTaK90o63aiBpra8BGey2x9uqrGx3l5jPHOguIttdZABdrq7PvT7bWWnYj2V1JrLcUf28BL7SW8MLgu+BbRyH2sosHbG4jR4DXd8zRWRv4JBPSd45msWQIdX20tjzrPyTw5RFeGHgnZ/dXE+2uhqF6/N3VXPhoIamWBrIHGu1owtZRTaizEn93OWu9Zaz1lrPWU4m/q5ZgZwOh9mairbegIDlxcB+Jlt0kWptJtjSSbGkg1VJHVu6H5joOVMKBcpsz4ECJc4v3F4GNAns9c7Bh4zs2f0/C6FhHzPhT6/FVvNX1uRHsrMXfXkegrY5Ie4XxOXCwiMsHyjjXfRsvj70P/5cOk9I2bEnFGBmLm0MpBeqebHoAkQCbrFrHlpAp+JxLJKoaLa29rEpTnod/WWB56kOsdr2V1YNVrHeWEuoqIbq/kExbPdGefTyx/y2saf1I+Ix9uRZ+ZjX772UlfxY49LPXuWpHl4qzqzKnW0hxacxQJkI8mySrzmJqjLz8FMmHB3l54Je4IC0lgBwsgBb5+CUeSCoJd3pDgOmsNALHBBIDiKuWzT2+FoAkOneS6Cgi1tpMrHU3UWNoJQJIpqXatEl2oJKLPSU83Xcrvi8M2T2QuAgpr0jz9eFi42wx1NyBTMra0rhIUAyIeKnOF7n8xT7OzPwel9oriXfsINtdQLgtn4utNSx37SHc3kiitYGcQG4+CuzR9gbCNhoJdjTj79iNr/MWfB37CLbfYvctcCRa3RBIHFAcWDIH67DRUmvAEXjcqCZ7sI7sgWYyB1T7tM+GyjcSLfre3UTbmu367Pc7aj2elhPtLCPaWUKoqxxfbyPB3iYHkLt3krpru1ksxSyXWhv5Yfcvc+nBj8JLD7vFd7h17FpLY4pZRPQeO4B4JfGeJZa7agAhSSq86rqvyN3yPQ/fu48LYx/kcvcdrPcXEuzdYUWvvv3NZHpvY7XvLTx39I9IvPAZNx8jFNr+h2tuojYHyg2O/viD61wkL6Z6pkRXrce6IOKEslpxBiGVsvojbrHQi1/iwvE/4+Xe20mq4rc1H1oLoa2YdHspSdPsFUS6qgh31diIdNYQ66wh3lFFsqOCdJsb+ny8Q69fxeisINlZaL+Xat1NsnUPkc46Yp1VpNrqoKXGViKGW4t5oaeWix//b7CkAsSwt1xWMx6yllf3J3qHbLbdBfZJdSuRo61KhMuPE/nnKX44/C6WDu0h1qfrvJHowZsIthbh67mF4ODb8HfvJty5y1K48fZ6Um31ZFtUHqIcvzumW3eRbNM5TQS6drPevZvVnj2s9zQR76izCcF0Ww2p9hq772R7nWUb9X3x9l02Yu1NvHok25rg4G44sAe07ufgXlIttxJvvZVI+62EO/YS7thDuLOJcFed8TPWVU68q5h4Vz6R7mJLgvh76o23sbsLSH30ZtifDy3FxPYXs9JWw/Pdt/PywodJPn7CGuhp8ZTcHO2zmrMcOtqfqollRWwSz4FDHR8jiaRrqCehlnyqgjd+iew3Frk4+X6ebdnGxfYtpjwCrXeQ6GgmPngrz/btZfWLH4Nz33OVy+qpFl8hop3Jchm23G//hON1Lpz0lkjqKjWsVMXlq0PeSjMtLU5Z0VAYwi8T+5djnJn9AKHOJmgthjYBpJBsezGpjmLineVEuioIddcQ6qqzISJLeAUgAcmBqcJe0+uvd8QNIKWk2itwQtREpLPeQCIhsaCtQynREi7M/hbZpxe9+EqqX9ZDSdxrAYgaFsQ2Mi7GOJWOX36O5FcmuDj2XlZ7dxEfLCbRl0eo4yYC7fnE+htI9N9GsGsfa917We/eY3TUHEe6VcBW4FvhuUflcLAcWitMGYmGEkh9r7+nhnRHPrRth/Y8aN9JuqNwE/2dggp0y6XbZUOg0ljrabLfNDAeEBh3kVWCo203sfY9BoxQp65rt513BSClxLsKSXXuJNmVz/KBbfjaipECTHU0uMLJllrMpTuQB4MV+A7czPP7izk/9154TIHzC+ojxLpfcyE5C5GTfEmpBND8IZsLUTtWvysYNqsTVY1XDlnhs6S+Ps6PRu/kTEcJgf47ifW9zVnezkp8PWVcPHwnwS90w+XHbFWj1qRoN6t/JUAkIF6K0wq6nN3R78tPVMQvXzDnM2ZDPrde/fJ3OHf/3Sz33EmqvYp0e7mBQwBJdxSTVEamq9wAEuiuQ0wSUGRVBJBsuwOTgPR6gbH5fFkk+31p0LY608ahrl2mWdNtVXCokXDvHmKf/xisP+Z8YNMUihY1HbgRgf0E/fHaL4lGIrI/rZy+Z3mjQVJfe4DlsT9iuaWRbG859OWRHMonNlxOeKCBgK6vvYlE5257LOENdeWArRKRGgeSlgpXaqJyk7ZSUh2lxEXX7lJCPToWQsdWaL8B2m+0x9mOPBNeaXk7r7uCQE+VgUmA2jzCXVVk25QidQAUvaRYBFRZDSm/QJfGrldYkGRnManOfJJdO8kOlRnoV/aXEm5vJttzJ3TeCm210FHkZeu2kurbwaWeal6eei/+r4zD0nPWTUV0Ew0tHthoLqHn8mpUzRG1OrbcBIR6GKtNlarP7XNKKCWeg0eHeHn4VzjX2kS4u5FYdx3J7nIYKuXiR29ibeJd8Ox9toZGa22UZRQ4za17DTZfl7swd3ruY1dWk+kiNPRlTpSEbK+kIPoMkfkP4ZPpb62GgXrSncpW7STdXUqsq5RQdxUCiLSejuHuCmNytiMfjVhHGeHO8qsaSgCkuhqtvit2oIB0Z4XNxay1NhLurCfZowRAJckj74FnPmlBuXzai+pkbskI3ZX5k69Bop/+lughJ031SM56aFL1q5wb/nNSg78BPU3QkU+m62bCfSWs99ey3ttMuKuZTFsDaNXigTxC7TuMVom+GpJ9TcS7mwm2NrC+v8YeJ7oaSHdVkeosJNN+M5n2G8h0/Dy0/zy03QBtN5Jpu4lMxzZSHZrr2WlaPiZXqLuEaGcR4bYdBFu2ET6wlcjBrTYRmGrdBl159p2a95C7muqrRNcR7Kpktb3ceGZ866rZcLGk/OQl6PxYdz7hnmIDeKBzL+H2O4m13UpaZSDyKto10/3/km7/OeL9hVzuv4VzY79H5stjth+I5E9S5/jgLIr60qXkQtkut5I397oBwnNyVAakoaJEsqrdet7iy5WhO4n3lZEarLbro7MADlWS6Skhcuo/WlcU/d6lgN+aWPxsgEg+7Cx9TDiVCLl8tK039laKCekK6LM57Cn1pqzCPw4RmX4vSwoauxtJ99aQ6Sol011MqrfMABHoqWG9VyCpI9RdgRgn10Aj1lFyVeAwUHVUk+7Za5mWRPsO0t3FRLt3E+y5lWDfLgK9Daz17IaH/hYuPm7VnBJoFUSL2BllM67hT59e9poMWhXrxSfJPjRIeOB3Sbfshu46aC8i0V1CoK+a9b4GfL3NRDsbnYZtKyPdmUei52biPQWEZRm6a1jvrGe5vZHLrY3Ehn+RcP8tbib8wA4C+28k1no9dL8RBncQ6akk0NNowbK/bzf+3lvw9d1CoG8vgf49BHsaCPfUkuiuId1dTqazyEBLWx60bSF04I1Eu24i2b+D1EAB0d4CAp078XUU4tOkZLfc5Arjo1zmWKcUXLl5AbJmod5iAr0CUj0BuWQdil/2uoqL9lLo2k6m5Q2k2n+BdO92/B2lXGrfRWL29+Gro1bek0jEyCTlp7j2RLYNQyJFRk0Kvepbiagstv501NmSVFecouW/wIUfwmf/gtWeUtZbtsOhCtBE4oGtZFpuIDhxJ0vfOkI4eMHm8TW/8rMBol8zJSqAyCf3AiRVYOY60lg1pkCTm573Yhah/OI34B86OT/8W5xr20usrxH6q8n2FMFgGdGeMoK9lfj6am3ocbSnhHRXgQ1ZGRH+qob83r59pHoarYgy3p1Hoq+ZyNAd+AaaOdfTxNLEb9rkkm1Kk4b1jNv5QgBJZLwNQD3Cv96DeLLkbZlH/DzZR4aJDP0WdN9maxfoqUPaP6R4oW+XgTba00CyS8CpIdtZSaq/iPhgAdGBIhM2X5c3M97TZMK+2r3bQO6XsA80ERxsIDBYjb+vlIt9jVw++iHOHP0fNs4e+2vOzf01F4/9FctH/4K1o39CYOYPCYz9Dv6+X8anyb2DSgTUgaohhhoI9exgvXc7Po2ePAI9eYR68wn3FRDtKzZeiYcacVn/rkobic5qIt3VxtP1vnoCvfVEuutJdNaT6qgl1VlNQuf2VeDvyDfQxfpLCHcVsX73zcRbS4iOvxOe/gSsv+S2V1PK3eaO0taFUzsebHg43ky7BFp013DuWYqQukSav5uBHz3I+vHfZFUKoDMP5NJ/JI9Y+82sDNTy4vT7SDz9oMm5Xw2wfwbTr7MzDEa6misWxC5MwNmwMLn3BZKUazOpb9e65pcfZuXev+OZjrey0tVEqq+ajPzjoRLiPUWEe8vw9TliCiCRnjJS3QU24t1lRLsrr2pEumuJ9ewhOdBMrCePcOcW4v01RIf3cXloN88PvoXApz8CF9R0IYlaNkW9mEoaKPKvXzfzE8mo2zf3QAHlS//A2ux/InigzhV03pVHtqeGUE+TaXRpdwEl0V1FuqvSwKGj6p/8A+VEhmoID1YT7K8k0FdBeLCO8OEm/MO3sHJoHxcHbuPs0Nu5OPluAif/mNRn/ob0l/tg+XFYfdEbL8CqxnOw8jQsfx9e/BI8fi98aZDU6f9JaPwD+Pp/g/WOt7PWuY+zHRWc7ytldagS36EKAkNlhAdLLLGQGiol0V3gjRLEK4HE8auacHc9a32NrPU3EOytJdpdQaqrhHRnCQkpvZ5KQkNNLHXXsNRZRWigllRfubl0tLyJTF8Nl+Y/TPrpT0HqsqvgCF22tqZG282pYC3BSIdMLC3es5WCScLErIe1lbLY9N2L8MMp0vO/xtpHt0KPJlQriQ/UstZfy/nOBlKf/4htnaFCSc86/ET+6kUvBtFD11XDlZyYSXHoNYBonkSi4LLSKhE25Jnd0z5350k9usjzY3/AGWVAuivIdBdAXz7JXmmiUoL9VajsQ8dIXzmJ3kKSPYXEesuJyqpczeipMdMeHdxFsDuP9Y43E+0vwD9UxdnhvTw/+3vw9AMQPKPmUWSEDrOGyj5lbYbW7uOnkudnveFlW8IvEvxcK0tDbzd3KttyI3Tnk+gpJ9DfjG/AuTvR3l0ke6vMH870FhHvreJSSx3LvXsJDu4lNCRNXMx69834+rfhGypgbayWlZk7WT/1BwQ/9zGS356H5/4Zln8EIc0uez6HbmTzkIq1Xsra3FPNHc65FPczD8PXjhH+ZA/rp/6Wx9ru4OXBO1mbejuh6bcQOiw3rdw0vcAhPmZ6dprCS/YUb/BL9W3BvgazjP7+BuOfeJru2Umydyex3mLjdXBkn9VGXehsZqWnkWg4+/l8AAAgAElEQVR/FdnefOi5AQYK+VF7E2v3/xU892mIvuB6Msd91g4sF/ua/pYFSav61lkPFxXHrdG3XLJkWP2lBR25Pefg0UGCw2/D39ZoMd/64K2s9zeR6CojPfsr8MRJW1hl2bLXYPN1OQTphzcPez2XSVCmwIYKykT5K2ZOKTerk1n6Lv7PHOTy8C+ZH20A6dlOujfP5gCkGX0DNfgHqgj1a3a7mERvsZngWF8VVzOiskrdtUSG6vF1F+Lr2kp0cAvLvTfzo7HbWfrsRyHwDKgSQK37NVQ5l3VrloNZr1r0NQj0mm8py6LdWZ/7JC9O/h5Lw7eSHa0g1v4GGMoj1ZdPuL/WQKKYINTXbPeZ7Csk1b/d/P611hJLYEQE8v4qVjuLudRZyNJABcvje0k++B/gKx+BZ4+D//uuMZs1lfO692hNkDwMrU60NqNXeCO8RCPy5dWxRn661v6sQfSitwfhN4h8vp31U/+VsyPv5kzf21jpv5XwQJNZg2iLXJSd0J1Htnsn6Z4C45sUnK412F9DpLeOWE+V8TLRt5NY/3aiA3kEB4rxidejt7M2eDuXuvey1NnEuiaQ5V733ES2P8+U6bnOvayc+jN4+XOg5hCJgDU9F0A0TOIsw5rT+HpFHo1iFK2CxeKVVDrrMlsCidrePjrKub63s9631yo/ZMEZqiMy2Ezsof8Boe+49SuvwWRvHkT9ZF13buvMbh/QBag8YNXrqKElkl4DM9PC7hJXVEem89We9NkHSN37QWKDzdBbAN0qENxOoreA4EC5EUxEE1hkVQSSWF/FVYFDgBJAZJUiI40OeAMFxIffyMXuX+D8kXfAD+bNLEuRpiVU2nBFBYQJVUzJiniW8DUI9JpvqT5t7Z9JfPYj/HDoHVwYv43wdA3BwZvIDLwJDm0l3V9gbl9gYB/rg/vwDzUQGSoiPaQg+9+Q7f6/oP/nYXArkd4iVnsaWBv5VaKn/pLUI0Nw6VFYeR4CWqUXcQrSEw8THGUU1fFEbYDMRVYFhGuCLQ6aK6ljNkMsk7BCwbSWxKpTSuwiBB+3lXvh+z/CxdH3szr4a0SGfpFkT70VKtK5Ezq3G0hkSTThGeovxT9QaYou21WMMkWyHAKGf2gn64cKWD0kt62KwKFmwkP7iA7eRrB3N6tdtaz0VLA2WEZwsNDiVK0/We65lewX7rGl3lK4ygpq2wjZhNwwS2LzI86TMWWtxtsJFc+rQthlu9RoxXVb+RHhz/xPwlNvs0VW9NWTGHkLl/puJTX7a/C9Qbdy9jWY/GMA2VjgYggV0QWQNWclcl3APTdFDFjSmgkz7apYfQ6+0odv8teJDtaS7M0j03ezaVIBISyNMqhjGbF+N+KyJgOVXM0xMlhNeLiO2FgjoUNVxEeKyYy9mbNdN/Hi8T+CpW9btaYW7jjbHCezvmSbZ+bW4hvRN/Vr3WxF7b1cHOatRReznGCKMVqWPI9v+le5MHQna6O3EhirIDqyg0D3z8Ooywzp/oKDjQQGmwgYQIpJHfoFGLoO+q9zQBnaYe9dGn03a/ffBd/9NFx+CdS+VJtYumpw85py+UYrJldvrOQFSC07PuGaiGpBqbSvRElDQMlp5Ki2184kSce1BuYyRF6Ey9+Fby5wee5veLHrnSy330aqvxm6S6Bnh41M3w5iA4UWo4QGHf/oLoLuQpL9+YSH8vENF7J6uIjVw2X4hlx5vWJEhu8ge2gfkcEmUxKrY3VGKwZ2wGCxxSO+sV8n/vVJp2yzKfwh3cUVi3gFIKKAZ02sY13MmtWFBRPNk0QduKx+68JDxD7xYWJDt8LoHQRGf8lcPsYa4BMfgOQLr/BMc/x3nlWK69zPu5jDXUAOTnpNFyEYeBOJVz7t+YLq46Qafq+Vik5dfp7ww/2cHXsHofE6ksMFMFwMh+rJ9lcbIeP9+SQGK0gMVJE4VEnsUOVVHquJDCgoryYyWkh2ugRmKjnbu5tL37qXpLZgyAm4lTXrfpRk8NYh6Fb1unZa8jSVYd1r2qbHJlXm2kZtn75lEq77i0qlg0+yNPMrpMbrjPkM7CEzWGpZqdBgCb7BcvyHqu0Y6S+0ib1wa4mluePDNxDr+39gVtm+Yla6dnFp6vdJf/soqD9yKkTCr7okL7ZQutMrstNLEnaR2/iXm3U2fgm+Wrh65aO5r9h8NF4bcVyhpTbPsS0rLr1A5GunWZn7c1b63krmUJNNtikFnBgoIDZURHyohPShMjhcTXKwjsRgnfEgNFJKcLTERvhwqfE0018HfQ3QI6+ikdSAOzc4Uk5wtIjo0M0k+7ZDbyGx/jpWFn8bnj1mnktOHjPaPiOrqUFHDyW7tMAvpcV8Of6+KkRw9xeG2LPw0oNcuv8veHbg7Vwc3kd4uBr63kx48hYuP3GvWZ71RIalQNqslegkmU/FVgSQq/9TQB+3jSmTLqsl+QtFyTz1CEsP/gXnx24lMFxKWqa0Twvsy8n2FZAa2ElS5d6DHkCGy22WWTPNr2sckqtWTWSwnPj4DtKTO2Gshosjv8nFpx4l4CmZjXy1uR6qLXOiZcLn5dklVnpVR7lfAr1ZCiX2JI3am5tLXLJmz0JT2LJ3genbYLQYBhpNAOgrJSH/e6iapUN1rIzsYn2onFh/Hpkel3ZUGjw+mkf40E0wVE5q8DbiJz4M35kDdT5Mhm22WNfvmOUlAxTzKC70wKzrdYJwdTzUd+s7AllYkfepG9YXqhXt9+8n+sm/4/LAW0iN7iNzuIZY906ivfkWZ6WGS1lu3070UB3hQw2EDlcTGiknNFJCeKSE2HAJqcFyS/nTWwc9DeiYGagmcajczgmNFhAbzSc5tMMSOqn+Utan9xH+yt/C0jddBa8tB9e+NRc9d9/F4bpMgcSuVyDRCxvE0Au6mSiZ6Hnr65V85jTPzP8hL/TfYpk6+m9k7VAVz365i0T2slUeBsIZ2yrFyuGzKbJJ37UCRH58VN2RHCNFcU3uBF+C70xzfvY9LA3X45f57Soi2VNKpr/EtGxSbtZguRHrdYFiM4g8gMgnjo/l20gdqiJ0/EPEL71o/aZMw9iEjoRIvvmrAKL3tDegJyy6BblfapBpANF0rZUFrZJkBbc7t9ImPlLfmMU3uQ9Gi2BAmrIe+svRvfkP1bA8Usf6WL2lT02w+opgaBccbiA6VoJvpIz1Q7eROPmf4bE5iD1j20/okgJagOix2dSkFfFpnY4uxpvI3SwTV4MRTQLr67z14i6DKfdFTRdegDMPE/9cK6Hp9xHpaoYele5UkBwsZKW/gKWhYqLDlabUoodL0ZDl0BBPk0OVBohsfy301ZoHkRrMnV9CdKSAzHgR6ZECkoMlluZeGmnkR3O/SeCbYxBTwzq/xZGZ5IoJbA4I4pOWnOeebxw9OrhmDHGS2hE5ex7ijxH6p27OzvwmlwcaifQVsDJUxeOL7ye7/AVXaRyJWB4jJYUopyiTuVaAgPabCKXFMKFWKk8r6Fbh4jeJfKGFy7O/wuWhSlY6dxLuKSQ9VGNDLlZ8qIzkcAXxw1c5hquI9FZZajQxXkBoZIelSnnkHtsJS6tdnYvi9Y81i/cqgJjr5dYnyJNyNNdzJ4TZHECiasK8ip+EbdiiJg+XH/gYvom9ZEeKwbRlFQxUkRysxne4hpXRWoLTjYQOK41dQLa3FA7vIjVcz9qhCi6O30Lw/j+F7y+4HrWpVeu4KBHVzyp2MJAat+ROKJvo/G9dp4RkQ2leLUD0dfZF+iX9oiaLFXsG3A6za98j85VDBMd/l8TQbWQPNRDpL7YYI3K03uK+9HA+qeFikgLGSBkx8XO4iuShGlLG7yrSQxoVHr/L7DzFjAIH46UWQ64N1bI03MgLg7dx4fR/gR/e56p/CZNKh60DpQXmuHUlWrPuGCYllxvuJUcb9R9Tlx7F0IqzHib7T21cnvkNLvXWszLSzGMje0l8tx2C33W7pwVd11VVIgmA1+hiOQaqeEyz7M5HVDcJBZbL8NKX8D30V1yafSsX+vIJDOSTGd5FZqjBxSCHSkkOlxE/fJXDA4jqnGITBQRGCvGP3Q6PTdtKPtMwopRUssBiluHVAHGvb86USPu4lpVeYki3lnAdyjUxZfe59G1emv0g/pE9pA8JIIUwUAoDNSQ1nzFax/p4DdHZBmLjtbZoS6U3HK61DNDZwTrOzv82PPMA+J51lkPdTuKwnAGVUQokuq5XWJBNbta1AiQHsmgsQcKv5MXKxv7rcl8StlOvD0JPw2NHuXzs/ZzpaSR4uIHUzC0kJ6tJH94OwzeRHd5pdDCFN1xDXMmT4ToDilOApcQPbx5lBqjE4E7S45WsjdZxabiB9dE9LA81szKhXmV/CuvfMIumWbqgJnvNgiYIxZIEtPmoaTSl7jUEkisAEX2Up0yoF0D8AiSfg0ufI/bFuzk3/m5e7N/NC4criXzyt+Hl+yB0zpltTR0pJLOJQmPA1f0zAstMW38usVN7QwRA2wpr5ZbM2+MnWP/EBzk/Usn6cB6ZkV2khxotQBcxEyPl1zAqbeIpKndtogDfZDnB+d+Cs582S2baN+eOGu2037cAolvPaU73MAcQ90xkFUu89I+2G7ZOWZeJmZZdgR/cy5nx38F/uJnkIQXaO2CokKyC1uFGgnKtJqoJTVSRnKwl0VdtFQbpkRqWBqo4N/F2/A/fDckX0W5VyZTbi1zrps8m4Ly3gaqzICLw/3oLovtTuiIUD5MIr0My6LZ1SyZtbkEC5hcvZU1SzxF+bJYfHf+PnBt5C6HRvTBZC4e3wMj1cPhmGC4iPVxpFjIx3EB0pJ7oaDWRsTIi40VEx4qIjxWRGCkznqcOlxMfLCIxVsHSeB3nDzcQHN1Damw38ZFaLkrZPTEBseeNF/6E5ntjqOmDwBHJlUIYODyQbEpQiHaK2BJqdapFbNotLfgkvPhpgp89wA8G38HFsRpWj94GT6gJ9osbKT9tuKZK9mu2IMKBJqiypu/E3iiJeNQaNlou2vc80X/q5vyRJtbH8yzjkz7UQHywhuRIHYmRSuKj5Vc19FnNzCoTFh3PJ3Cknuin/gR834JUzK7LLIdTJUbkDYAYup2PoocCiAmjnlga2+u6pzcCApTmGi7YnkwkzhD+UgerU79O4NAuEkPFZIa3wKE80oPSms0EJxrwT1WxcqiA5Fg1GZVZDNSRGG/g0kgTq/d9EF76lKVmtVgzqOF13VjKuhovPdflGJsNIF6ud1PnFfe+g/Xr/S9L6U+qC7oSxk77EtdKJm9vMz1MaxdbpTUElDMknrufyx//c/xj/x6mmmBkC4y+EQ5vM4BkDlUj/uYAEh6rJDhRQnCygOBkvgPJaAmpw5WkDlfbMThcweXxKi6N1jgXeawRFKMNlrL2iT+Giw/bfiYCSMTbFTkmoklvmdVQsC4o5LIyjpfGOq0jyRFJezqGzkLoOXj+YZYf+ihnJ27n/NSd8MQshF6EkLrVO6Wv/Mw1AySkCgDjjITIbylUlZL7c/6BOpp/7xTnjt/B6tQ2UhPSMLVunmS0kfg1AiQ2ICJXG0D8c3uIPHIXxJ81Kyba/WsAousXMe0+vM+oTseCVs1S+5VilHU8R1pBY+QF1j/xF0SPvIPAUJ2lPpPDbyZ1eItpz9jIbkKTuwhMV3OpZ5tpS1kWWc7k9G4uz7yV4MMHIKGgXLu0OsuuBgXy/kU6m7fIXVCuosEL0MVvfUYjx/vXCw6dL1Bo+zaXtXOFBrZE3wiSJOpXax53LYpMNB2npt688HFin/pzVoabLDGSHruJzIjc5zIyh2o3AaSW4EQ5vqkifNP5BKbyCU8UEM8BZLiWzESzxWMrY2WsjpVZZTCHqmC6kMxoAWfHb4UfztoqwFA8ixbwqVWpFzo6gOi6cgDxKj1yPF2JqHWQRyvpAK1n0vp47Wf/wuf5wcRv89z078Czn4DIefArRPBCh/8VABEBjY8miRIqEdxlRmVZzJu5+AOWHnwna7PbiI8VkB1zmiI62kRsrIbYePlVjcRoFYw2GUAyR8pZOnorPLvgUoK2/NW7OF2gN/t/xYJ4cYn3+gZAdK4pU1ebZmWllni/DFllRCKw8n3WTn+A6HgzsdFdJEcryIxvsZEYrSEy1oR/0lkQuRdyKZK9FWRHmgjP7GP9vt+HMw9BTFsKXJkMywm96OcEXxci5lsazfnZnqXLzYM42l8NPLzPbNDFeRf6Xl2Hl7qzZuY5QKrmyWbr0y+Q/eExzp1+PxfEg+N1ZKdrLHhnpJHMcAMRrSuZqCM0WY5/upj12QJ8MwWEpgqJjZeSHqkwDyIyupvg+C5CU8XEJgqRC8pwBRzeCqNbCY5Xc2bud2H9Sbt/TYMabHVRqo4wLSiKeRbEAOLmgXQfup/cJKnOMsKqIkTLrtWX4IXPwsuftyXSBC+5LKzR2GUyr9mC6EeNSTltbZNsTgvq4izRvvQjVj71btaObUXZJgEkeGgXIk70WgAyVgEjDUZUAWR54S2e2xIgq15KuYvTtW0IgtwFuSqvBIi0qLkZ3mdkPdTcOKNcu24ivQTZFcgmrEo2ePp3iY9XkhitMx86PbGF5MQWYmMVhMZ34RNAJmtsXiAzVkFmsJzsaCOBI3cQ+NyfweVvubZDpvlEqNyfLjYXdG4Gh3MfROsc40XfawGIZEyf1y1vFiRl8DSZakLnJThU7xTXHmuWRVsmtfYtVr8zzMr9v41vdg/B8SZSU3tgtJn0oVo313GoiNBkqQeQQtZnigkKCALIaDnJkRpCY7cYQCQX6fE8A05mRHzdbgBJjxWyMv1Wkt9dtNWAiiC1qYEtqLK9F0Q3j2YbINHzV96XQKI72pBV3ZdcrrWXwH8G1IVRnek9vidto4fAtbpYLh0qAhuVxUOvRFkmWV6rcXN9hfXPvIfgwjbSE8UwXk9guN6IGpuoJj5RcVUjOV5pAMmM1pIWQE7/GsmLX7OLyajn0WaAiB4mCDmAvLKuTEG5neEdBBYtEEvZPuhx0iq3kfOTUYDwfSKn30VqopDkWC26jtTkzSSnthKbLCM0VYt/ahcBjaEimKgETZiONeA79g4y39TWYS9dabG0YSFUfKdgfNOw9xw4JNC6vBxANhhu4vD6/+m7xCMNPXb/5SpruCSFZNC0bjpDMqJ9Gl3NV1Z7eYQeI/Hdfl4+8uucGb2T5Pw7SE40kzpUQXa0DH/fNqJTJQRmSvDNluGbrSA0XWE0yoyVkRqrJDTRbO5oZmIHjG/DvS6LXEh2fAeM7SQy2cT5U/8NVtRVft21LY2onsxZCtHFgcRztSxod5edo9VmK2LnC0O54SlPR1vJtFqnrhPj8rUBxE2oOR92g3Oe3Akg8qWNm/41Ap97D+GF7WQnq2G8Gd9IHb6pOqKTlVcFDoFKgpk9XG8WKX2kEt8nf5ek7wemDV1libeQRoTwgKvSGGvRLSJ66lcHWQsTEB1EZ7OEWmvu2h9pP1jLM4m6y08Qu/dXyU7m2TXEx6tJTu4gPrWN6HQhgekKA0hoopFAfxHYPZeQGq9hfUFroxdd5xO7rlyGKpel2lw57SYFxUn9bE7bO0Y6cXbCYRLyuv9JeLwCDvt+A6atu5CFdb+nCnJHpjjp+JrbxXajFiFkmw1d/Mzf8dzku1mefgexid3IYjJWSPzQNuKTRYSnyvBPV9sITVUSmxAAikiNlxGdqCc6UUt2PB/GbyY1XkR8ooz4RIkpICYKyEzV8OKht8D3pyFzxs2Qp5MkE25qM4dho8iGS6pXHY2kSGQhddQ92/2IcJ5M5N7XOe48RVtrpFi6doDEbPGit6xOv+RZkZxmMuD4zhL6zDuJzefB2G4Yu4P18SrWj1QSmS4nPnV1IzVRZQBhvJaUtNMX/iOpxHmb6jKOW5m3R5GfBBBHQyPYhkshCnrpdVcjKosjpyxiwaxpnaUnSdz3yzC5xZIOiYkaElNFxGfyCB/JI3CkGP9Mk9X6hAcqYKoSJnaSmq5m7eR74dIjZj0sRjNGea7Uj1kOd4GbgaHHV0AhhF39Xw4gpsjEOE3yqu5J5bCebtEuUcpxpQmTZp1Map2stxGnlWQkLpF+/iFevPeveGb47QSndsOUXKRtMJVvHkNsqsomTAPTTYSn64hPVpKdKLKhpE1istImCxFoJouIyw3zZILpMpit57JKWj75XyDwLbd5qZKLXqcTiZ0DcS5m87J9KhfxQOKx1cTxCv3c5/SegJGznTG0DEJrT66x1EQWRGJj+5YKGDmYZlxgJLNmV7T6FIGH3k78iCaVfhFGf5n16Qp8CyWEZ0qvASCVZIbrYKLBABL/yp+g7rjatsCIEPfUn2dBHCFkQVSyobUhTric0Hno1sEDSMx2kEgQsSSn61huMeHK0yTueztMv5nURDnxyRoSk6XEZnYSnNuCf26nA8jEPhKH60ECMLGV7JEqC+7xPWrmXfS5wlhdjOcimJZxVkOv/jhzJQhe4G6IvTqQODdSFlKiIffOS9/oorziA4UdcjWdIxYkk9GcTRS1EHVLYiWlZ1n/+gTPTP8WgZk9MFsGozfC7E4k9FIgKgwMTu4jPNVIfLKK7EQBTOTZMauYZLzKKZupAmIzBUSmK4lN1pCcqoIj9eZl+KZ/EZ5ZsK6Y4q+WO0sRS+w8Vjq6mKLRO1dcRd2SznG8lkA4emfScVKag9K0ne5JsZadp+RJ+NosiH4i7NUt2VoRXamG139VP2SLlC79M74H9hGd2goDvwoj78Z/pBL/qXzCs8XXBBAFhEzuMoBkvv6X5hKpKMQAoopbj9l64bUB4gmJBxB9TABxu0gkCXo70Cq2Y/kZDyBvIjVZagCRFRRjg3M34p/bbgAJTtxOdnw3jJfD2BthoYr1+z4EgadsT8L17BXmOsY5Qde163lOs+X0ziuEwFuC6kovrg4gBrLkZbfc1eusLtdYbtcGeFXMqeBVrVWTMdsXPpnN2PqSUEaWRWCKwvkv4//8X+Of20tmpgCmboLJmwwgqnaOjN+K6BGe3G0AscLSyS0wsQ3GC0iMNxKbaDQaxmbzDCCRqTqbcE3N1MNMoZXs8MW/h7Xv2e9e2HStopX9SXFYSY7WyXi1axZPuSSMc8oEeDFaMx1K3/vNauo2teWH9iYRraUYrimLJeK4qlepm9QVjnp5Z110JrgK5z6P73QzkfGtMPjvYfRdBI9UET5ZRHS2hMR0xVUNaRdNFqand6G6oPQ3/952JpIFMYFTJZ4eSOF6LpbsnWnMTVksCaRbn+y5il54ogU4mqXQ5JQ2rzQmCCArT+N78L2EjpQRmakmOlNNcrqE5MwO4nM3EDl6M6HpZqITt8FMswlJcuwGEieauPTgn0LwaaKRDD51c93kG4spulwNPdbviY25c/SaZdqkgZQ8sGXQYrbe0U16msG0gycvGy/pwjedY0pUM2JaA67da3WPrqGF6KfH9jXWKTIO4bDtcaLYTtfn9nF3v2yZvfgZeHKeS/O/juIM5gvIjr4BpnaQnKogOtVEdHIviYm9JCbrSczuID0rEG2HiWKSE7uITzYRnykheiTfaBs8Us3KWBXRiWqYyLe6r8SJ34LlLxKN+FHxT27OSBRw9/cqgJgVcTQSONxw0xHO/njrnTIpuw31IVGJl+PDNRYrOoaI6B7hRXRx1cOKbVGWUlnGAmtzjXCsGCb3kZ64g9hMA7HZSpKzVab9FUO83pE8UmHfEZlrwH/irfDUIeuWKIFywuTRzNMIrqAy559urmLdJFtecJoTTgmC7iORWkcVpbZ4LPUCgX8Z4fuTv8ZLU00Ej1TAfBEcuxlmbyQ5sZ3YaAPp0SY4vMOC+fhiHWcW38aTn/rvEH8SUhHXpdSzwB7ZbNmAkVPVCd61KMMmbaYNZ3Rebuge3TZwcicEGC91vQkLDmy50hmvXkkf3PgSCZRgqHPcy3qmx/Zn37mJxxuAE82SxBKCk1Zpxmzb7PVHOjl/5JdJzVeTmLmR+PxNxOa3E58rJj1db/FndnIvoYVCQovbSR0phekqmKqxuZTkbA2RuQr8i4WsHy/EN1tCbKqSzFgJmdlaLszW4//a39iW1NpuIncbjre6MV19LprwvAJzEV1Bbe7WdZZS+y5oFoCuKI/NeuaaLIgxRBpG6BPh9E+/5S2V1LwnqQvwgzn8RwWQQjIzDTabnJzSsYbUNQAkfrSC8NFSfAsNrJ78JXhyzNYY54TCBEgaT4v/jLEyDXK7LE11BUSbCtxyBLxCeImJAljtuXfR7X+XfpHVJz/J149+mOen9xI6Wgzz2+HYFpjZ7vzqsToYb4DRfDJT+QQWannp1Nt47KE/Bf8/u7XQlkN1gqlr1hANbWwIonxht5+eSz++2qpIGwog7p7sS/RFHr/d/UiQ9D06Ry6Tlh97aJCMXPWfmO0t9xXvEwkyT36OCyc/RPBYI/GFbYSO30R48SaSx7aTnVFscgeM324AWDu5ndhcmQHDgvHpCpIz9YTnalg7kc/ayTz8R4tIzAggFaRmarg4V8rKlz4A4ccM2LonKQ9XO6fr+UlDVBCdHaB067KQOopUr/V3bQCRiJmZ1yo9XaT3i0Z/IVZFbpccQObqYD6P9Gwt8dldJGaqScyWkzxSdtUjfrTMABKY9wDy1Ajax0TXIZJoCByvBZDNbol47ATKASr3Hc790szrZZArkT5D4uzX+N6J/86FiWYS09vJLNxIdnEr6aNlpGeqbGUjM7Wg1YbTVQSPbmflvjqee+B9ZF7+uPWINV7mfkSCugFUWQyXTFBCQWlpCYGbzPQUkWcldK9OezpQXLlx933ufrQOxgmSA5IHEr2pm77qP31BiHD4svsa9d4JvET4iy2sCiAndxJazCO8kGcAYaYURm83gAQWClk/uZXYXCnpmQr0ngDkAFJr1mP9xA6CR4vJHK0iO15OarqSpWNFnP3UO0mc+bR5C8o+ilqiwZWkb26idTNxHUAcPa7oh591+9cOEAt0AsvFCHwAACAASURBVF4a0HNQDSDy9TU7uWTNE/xz1bC4hdTRSuJHaokdKSF2tIjUXBmpo+VXNRJz5Q4gC3WsnnobPHXYNSfecE2c16FGFFcsiLp7iICe9hCFPOHMvZYja+5oK9ekb5JrrtgtcxF8T/PiQ/fgn2qG6ZuIL9xA9MR2YvMVpI7Vw9EaOFoP07eQmakjOPMGIvflc+H0W4g92g8KjqXCcppckm4AcRZDOzA5cAgoEgBPlj1gGBA8cus67R5ymkFKVOd54NHnlbJWulpAM8DbZJpnZtypV/FfQpnAH1hxIFWAHPHBE/dy+fg+Qid3ElwsIbJQQlru50wJjN1mbnZkoYDAyW3E54tMqXCkBFVDJI7WETlWR+B4CYHjRUSPlsJRxSBlpKdKWDtWxEsnbmftu4fdQigVx+aUYY5GdvOeW5h77FVK5EiU+8z/ZoCIE8p7aFLFZ8Q3ThpAVFK2Cl4M4jtWCYs3GCBiR6uIzu0kOpdH4liJA4mA8jpHYq7MCBicr2P91C/C04OWI7/iu3vh0StcLKUynWCIWBuC5Qle7rM5cNhRfXWk7lMh0kG5WW59gf8bo6Rnb4GZm2wSdP3kTgKnikicqAbFXEf2wuxe0keqic38HKkTb8Z/ooLgwx+G4DNYxzNxSmT0LkYa0c055DSj6zbzyuvU5KJLY+r6DPy6fu8ynel00uLcCvUOUBCudkculnHrXTwUXQU0ch+JRuOEoxGi6q6iOjW1Vlp5nNVP/QbLxwsILFYSPVZO5uhOmCmCsVtgcg/RhZ2ET2whPr+T9FGBxAEl7gEkuFBOcLEMeQkGkKkyMlPFBOcKeWmunkuP/A3EvmcWLCfsuv0NgdeDVw97yVkS0cVInruRn3K8RgsizrrOJwnW3Eo7/arlkj2AJNetSZdvvhxOXI+EOjJXRfjYzYTnt5GcLyZ9rPyqRvJYuQeQWnynboOne627R07IjWCeT29CJMmR9XAGJCeTzq/yAGJafJMF0mSe+i0ZktIxsjGf279Cu+I+/0k4/jY4VkDweAHLp3fiv/dm4qdK4KiAcxvZI3tIzZaRnXsTyfl/R+z4Vvwf/yV45iFYWbkCDuOsxF0mxeXvjcE5wc8hVs+lqY3usjLuE3aJuuHceXbzkhH53SmbrwqT0tq8jbkrJSDsZ3+KcPxrXg4EEpYWjWT8ZLNhL610kdS3/orLp+vwHa8nNl8FitNmS2GiCaZ3kVjIJ3piK8mFPNLz+aTnC0nOl5I4Vkd0vp7IQhXRhQrzOCw+mSknO11kivXisUouffJ9cP5+U845gOjWc5jYeJB7IXf0LInTjD9bQfwvAEiALGvE8RkjctpL5lwzkWgfusfvZW2+0gASP1ZOeK6K0PzNhBa2kFhwhBFxXvc4Vk7sSCnh+Wr8p/bC0x1uUcyGL38l4HXC4Pnem+JZ08yirATqp4FEk2WpjCtcTGsWUdYkAr7vwIPvg5O7CJ0sY+X0DgL3XU/slGKtW0hO3E5qtpH4bDGczCMy8/+ROnG9CU30kTY4q/0qvASHSaMuwAuk9VDXJR2UG7lrtDe0TZlK9zyA6PP6jM7JBV5Zl/uXACkolc3JDfUEU4pep1/1nzqze1NNccFO/bb0Q9EAnJth+aFfZvXELgeQI+UwXQGTdTBTRXp+J4njW0kubietGGUhn8R8KbH5GgNIdL6GxLEqMrOVruTkaDnM5BM7utOs0tp9byf5WDdwecPF+tcCxBFKZ2uIaD/97xoBoh/QlHzAupuIEcZMS/OK8VrXHDKA+I5Vw/EbiM9VWpYiOJ9HaH7btQFEBD1SQuRYNcFTzfB0K6TPmxrZUBgeWFyFqjfP8WqAmEBtAoho5lkefY/ejicypHNd9bJpsmqynDxD8rN/Dff/EqHT1ayf2kbw3jcSO7mV+Gw9sfFbSM40EZ0qgvsLWZ/8v0mduhHfXBmB0x+A5z/t9loxRomWHjhela7dDN7cfclF0CdeARAxW7PhueGVWogvSn1LdnNDDpyjyWsLyE8XHUejXN9oS0OnI07m1Jwv+lVWHv5Dlk7tIrpQDrM1lso1kBwpJDOfR1JJjQUHElmU2EIpUVmO+ToDSvJYFdmjFdYBhvlSOLKTxNGdxE+UEzrZSOSrfw7ZM0YH0ws/yYJ4vNywKAYIj9b/+wGiX48Ty4RYT/qNWQbnhJo56JKV+QmR+fYCsZO7SR65gfBMuQVhMd3kwg4SC8XmZsnVev2j1Fyz1Ik6/MdryHzzv9uiJk3+iiAJW5TuzK6yOJbl8LSxCb64bzNfV5ILRj9PCnPCuPlohNbn9GJqDZa/QuJz/5W1kzUkPr6D0OIbCc/dQPZkDSzuIT27l+RcvblWodNvImiZnRpiR29nae79pH74WQhdtM4dmpHOxCOkUgnDhG4jlFaoriDbyZ6oamlgZay9+Sa954ot5ZopFrgyg6wO9loguBJO4Yu7NKeyYQnNxMuGaH/FTMZGNpu1phGvCYrNb+bcVytHcXM1Ya3I04XFniHx/S7OLNYRO14Es41WxY2s6dFtJI9uIXnsJtKLWwwoscWdRI4XE1msMJAkjtWQnquCuTKYK7KJR+YLyS6UkjleRvJEGZfu/RVY/66xIpFME405axzTfSZc4bW9uZmBUj5KUGyY5ddWENdoQUzCiGcS1oI+Z0HEn1AsSkp9YONr8Ogs8ePNJKevJzpTQXxxF4lTNQTnCzyAyM0SQF7vsZjssQoyJ2os+E1/408grd1rnQCr2lMEEjDcDPoVCyJBs4kiESznkohWr9I4r6Cthwu9Zn8qsfA/D49PEPjEW/EvbiN5agepE3nEFgvJnqgnfWS3ASR0Mg/fvVtZO1VOaLEGZitIHLmdcw/8BclnP2kd/qzDeWydYGgdXzyCL6vlrqou04y+A4mu29DjTa/ruQO/nCclTLyOJBbHZAhFde+OJFpfZDeogFrd1JVlzAgkVw8Q0ctau3qxTiBqUmA9gONPHuPsqSZiJ/JhugkmG+FoPtn5LaSOaW7kJjILW8yKRI/nEzpeTOh4KZHFcmQ9MnPlFt9xbAcs7iS7WAiLVbBYAcdvZv30bbD0Vbu7dCpBQp0WBPtEBtWpWkX3qxmoC/4/CRAZCi29EFnECAFTfRuCwSDx8GXX3PnRw8QXmkhMXE9itpTMyWbS9zYRPFpCbKHYAjbFIjKzr+coUDFfSWaxitDJEmJf/U9uua2shGbPdbTyAjkUShp4KterYVRcYieKkhqmXTwUGKmvIOLVdDaQ6PxYABUfJr/631iaqyB5qhTuKyZ8bCeZE5WmBcXs4IlSVk+Vs3KqjpAYfGQrHMnn/HQTa5/9Y/jBGCz/o9sLnCTBDJyNWR5QuUDWSVviN6kYSF0y5CuZPCgF7FkOA0cOIK57pLXv9DS9aVNtkJk8A2vfIqG9XdIqQLxKgIg80jkxZ3k00+JPu6JOKZ3Ui1/k4ifuIHpyB8zsghlNFheY1UgJJPNbPIBsJ7pYSPBEsQ1ZEiVgsnPFsLATjm8nfSKP1PFi0ov1MC93fQvhU03wo4ecxUyGScmdV0ugZBrNwUrvbeZbjqWeuvCsiGmNK2+96tE1WxBrTOilUS2TIqaF427f8PQyxB6Df2kltdBAavx6kmq1eV8z3L+X4NEy4oslJBcLrmqkFmR6nUaJnCok8MhvQ+AJd/+qp/EQq5lm5W9+HCAyyR5IcsccRV9FKD3NvbX5aCDMLMOzR1i7/zfwK7g8WWL3FZ8vILOQj64zdLyW9ZMNrJ1qIHq8DI69CY69gfjCDpYWGrh477sIf+0gXPoyiG4qlMzmaqOyrKvlaTpMUn2e1FZJpR1S3RvaMGdBZEW0j4abuNVOssJTStZUiQVtDbD+T0S+P8xL2l8ktXL1ABHwFJtph9e0RSH4iFoiQG4gS4+z8vl3EjldADPVcHQXmYUiEioxOb7NgMLCNjKLO4ieKDElFzpVQPREAZn5Emc9FreRPbGFxGmXHUwu7IGFBlh8s3khsafnIbPutHJc27ElkTVRvJhbcGhu6Sb+/R8FiMmV/H1ZEYFDWw2oc7hptYtw+eMkv/6nZBY12XM96aN58EADPHALIU0aCiDH869qpBYLYEGFcaXETu1k9TO/CivfdvcvcJg/Yo1trC731QDR5JmbgZX4vwoor3j+E9DiEdw8CpWB+n5A6ls9nJ+/Df9CGdn76okc2UbmxPWkjm8lutBAaGGvAcVcjoU3wOK/IXP852w+QDHM2ifehf/Lf0/iBydh5QnH9HQuThCYZadlOhRnBLxq1Zya1A2LAa73sJ7p7KglGFQ2HHYZvsSj8OQQlz71+zzzwIcgffaaAGLOfjwqBFpdmCJRVQObcQudIfyP/4nwac2GF8HxalKL5cidSp/aTnrxBgwgSvkeLyNwqoTA6R1ET95MZqEA5nfAyTeTPn0Dkfu3E7q3jMTx22H+Fli8kezJKgL/Mux6XqmJtxoWqrIjE7e19IpBJQI5UdBjBxbRUu6F3vnfaUGkJfT9qkpVoy0pMRWvZdVHVcszn2XlsTYCj7wbTpbB9PVkj94I95fDx/cQPVZN4ngpqRMFVzXSx51Pmj1WQvz0Di4++Fay5796RUHYvcv9CFi7HgtkJTWeiyWAKA5xhHMpUWdRRLhXj80AcoDR7UtDxzQ5Jq1+8R9Z+9yHCdx3KzxYR3zuTWRP/QLpk1vMgibmbyG1WEXqxE7Sp64nffrnSJ1+I4lTNxK7txj/6V1cPvGLXLrv9wl/tRWefdAqf4mqe7sAoXuR6GkyUW6jHO1NfN6It5TCzcHFuRpypUg9C+cWWP38B7h8qonAI38AqeevHiD6cbl8aW14rmVVMes8qcXJcnYkC4lv/iXhU+Wkj26HUyU2iRo9XkH6vjxTHizkWWwRO1FJ8HQ5wfvyiNy7jezxnbCoz7yJ5H1vIPjAVgL3VxLVvNP87bBwo8nU0lfarMsMGVUmqLGGytxjqLFXPOEqEF7NSSlKDVeaYkLykzXgtXY1MZ8jnbGsogxHPCIOnQdeIBl8maUXP8sTX/gAlx/aC6eLYe4GMnM/D/fmw8ebiS/UGkASJwq4mmEAOV4Nx4qI33szZ+69lcTL/+BkW0DYAIhm+VUOc6UOX6DQXI3iEEdAN8MqojnC6VUv5bWhbXKkdmARQMICiAJmE9RlePE42X/4ANmPF8Dpf+uAcCKPrCzdXA3MVZJdLCB83434HthC7BPVhE5W2ERj/HQhiVOFRBaKiJ9qJv3J98BjnfDsKbj4bQircYRL2arzoqINSxbqXnVpnjHR01xaN6wgOp0iE3yJ1I8+ZZWwZxabid5fAI99ANJPXj1AFIOpEljzHxpErOOI1uPo+lTgmf3ufoKnakgeeyM8kE/8RD2h4/VkH1CM9iYEEHkAkRNVBE6XE7h/O5F7t5A9ngeL2+D0z5P4+C/g/8QWfA9UEznxKzD/Vpi/CY6Xcf5zH3HN4DLnXZeS/5+99wCvK7vuey+HBexEryQI9jKcrhLLlhRFUYrlOLFjRYmduDyX51jOs2PHzy+2FSdOHMe27Eh2JCeO7TiSZoYVBAESIFhBdICoLGCvYEXH7fee8sv33/scEBwNZ4ag9OaT7MtvcV/ce8655+y9/qvttdfWPimKEmn9TkZCxGrSQC4GvrICFyFI3hUgQc/qgUKNoFZkR/3x3p/5zp6nxFgJEa2nMWkG3g3w+0kPH+Rq62/Q9+bL3Nu7GjQgXyvA+4vl8GYF7H2FzNd2PBNAHGkQOcL/ew3ZXWUMv/4iXN4T2OjGQw8yYZXwJ6n7iOctQEJwSAmGAJEm0bO9Ez0CiNZsG7lu1JBWil2G/t9hatcLUFNBamcpmTdWY8D81XXwlxvwv7aO6d2rGd9bSaz6BSbf2GzylvzqCqguwH9zqZWuezbh7PsY3pGfgP4/hLuHIXnZaESbfBgkmYWKZbbVYMZPs3j3IN5L+vrr3G/+Ja7v/hRX/mIb6Vr11S+aiolzdtJNBFAMoHX00hvTJuImD2pC/aF0mL4vMfn6R0h+dSXUFJHauY2YUnH2VuK/XmCjU1/dgNUgG4jvKie1s8Q45Xy9BH9XLpm9uUxXlzG1dwupNz6K/7W/AV8thTe2cefAL8Jkn82yVgV4E8lThzikJLUDs0qjKWGouZ/3Cg6dG1FKulmPrQ7VQ4V8IR4wyzoVU5ddp/yfADPqGMMWWjgfOMNG2GoBzg0YP0i29xe5Vf0Sk3VFZGqWwe4iUDRj52rYuQHvzZdxRbu24O5eP2ealk9TvRn2V5KQ3d/4y5A6C9nbSqNDm6rIbZVE1eOFzyAnUo8a4j1sTY+GBz2xtUfpfHlbijKNKe6uPsjEYLIbzvxH4oe/l7Fdm4ntrSSzbzXe3rW4O9eTfXMLqV3Pk9i9nWT1RpLVlST3lhDfk0ty7zKy1ctwDuTi1JYQ21/JWPU27u77EMO1f5/Rpp8ideY/wJ3/CeMHIN4N0SsQGzPBEeOiyOSTuZHthZt/SLL9hxmv/zATh17l9u5XuPS1DxNv1sKtertPn32cp/9fnRbyCbIcVJrVztZLYpsgwnAz0T0/QqZ6De6BxWRqVxPbWYH7xhp4vQp2rjf84O7ahLN7A+7uKkPsqsLQ7tW4e1bj7Kkis2cD7s7n8XZugzcrcXa+yoM9Pws3DgfFHMaIE2XKi5NUiXYDYPGt5sBsJFOC0pimM/f+zo8dUYRnBiB62BAkRgJoMY11euxcQdghYg2hNGvX6MjgNQDRhu7tOKd/k9G672GqutyCozoHdufDLgFkA7z5PO7OF3F37kAdM1eAqENjr6/F27ce9pfh7NxItu5HYKIR3CtkmWQKz6h7yRITZVOniYLGasp37qQnfasu0nUFQJXFlDa1/TAJY21w7U94eOQHGa3/AGP7q5jcW0Jq7xq8vZtgz0uw+wXYtwl33xqye8rJ7Com9WYuyTdXkti5koTs75oy4nvLGNtZxv3X13D/jY2M73uFaP3HSDV+H+7Rn8A98StkW36fdMefEe38KhMtX2Hi5K8TO/rPyTZ+GK++Cu9gCfGaNdza9SpXq/8JsbN/CpnLgTnypCd8D58bgOjBh4F7xoQROyjEapK0bvUxtednSO5fS6ZuIdmDhcR2FeMKHPJLJSx3rZ8TJXe9xujuH4aLX7fzX0wHAtEnrXQgSSyFMs2CMIX5Y0E0U3wdKAMB5R1ej4d5jRgN5gTCuQFdaDaZC4ZXDxlCnSHtcRku/1eGD34vt9/YTqx6E44xr4pgT67VIm9uw3vzRZxdz+Ps3mKkhrNnPXOi3RvI7N5GRtJmf4H5reje74NbO8G5Y6I+kvCKqsxokFByCCDmed+hd97tq/BainKmPDzVtVXXCDlmYdZNkre+yoPun+PSgRe5truA2IEiOFQJ+7QKcT18bQN8bRN8XZNfWyxpnuSrG+z3e7fDni2wax3+m3Luy3Dk4O4rxzlQydiu1Yzs38BI/YuMHHmVh0df4cHhrYzUljCxbxmxNyL4e5ea4yd27uBuzQ8ycfr38cds1XSL6Hd70Hf4Xs9rQs1Wg0hzPAKIA7d6mNr706Rq1pOpW0TmUCHx3SV4byg/7dkAkt69g5E9fwuv9z9C9Kzpc5Ut0+/LjEopcBIKRFum26xR8iXcQ0Vg+PnJzxeZYX7zRpe2mmHGHwnBYa4RRnoeuSjupBbxqlTMLbzLf8ndY/+Y4dpXmTrwMun9L+Lu3o6/ewPsLYU95fi7tuLu3kF2z1Yy+zbi7t0wd9oj0+pVUm+sxd+/HKe6kLGd3w1n/hhSDw2zChgCiRk0PUPIwCbi8+SOeU/f6Fq6sCjj4afTpNJZEloKaraukFq5Rfx+Dfd7/jW3Gz/JWN1WsjUVsEtOZoExFYxW3bUZdj0PO1+ANxTnfwG+qkVmz5tiD3x9E7y5DnZXwp4y2FcK1SVk9xeTqCliqjaPsbqlTNTnEDu8AKdxHhyeD/ueg+oiMw5Te/8uifbfgtFmM4v+XqI479oPBiD6TzPzY2/RIA7c7mZq708agGTrlpA5VPw4QHYpJL5hTpTZu5XJ/a8wffJHYVg75Gr9kd3xV0ZVLJMwOLAYkJYL54qCWgUCybsCRAfp+YxtoAtYBycEiMn7MULRLuSxSxxtRXdjxEdVCmIYRvfzoOknuLhnB6N1W3GPvIpb+xLerpfwd76Av3uz6QR37zoy1etIVW80lN0ngKybGwkgNR+0E0v7c0jvX8bIzhdItfwaTN6dCecKJNZJD8KiQce8S9+8K2/Y5w9imhKdXoqEN8GoO8KIM82Yp0rAQmIC4lfg+k7iLf83o9UvMbVzMfHdEZyGlWQO5ZOpKzLmlHyV7M4qk2vkfG0L3td3wNdfwn/dkv5Of3ULib/cQPx/rYc9r8Gul3B2bia+s5LpXcXE9xXg7s+D/dLcq6H6Faj/AWj7DbhVD9mHZng10uqKZ3qpE01HWic91CAS3CbfY7iV6L4fJ1OzCad2BdlDZSR2l+FrScCbmwxPeHvWMRcSH8Xrt/Cw9ruh5/dg+oKZb1AQS+WKNNFqx143Ewh/41dbnjf3+C5MEDGDrPNNjdhAe+hPhbi1LmKmGohmozWfoOWfds2RERfJcXjQSKbvl7hT/z3c2rve2NvZui0QAuTN1/B3voK7ZyvZ6jWkasqJ799gHNTMMwFkI96+l40GcaoXk6pZzET1ZkYbfgLuXLRYN4l0EixKD1e0JeAKo0H0xzO8dLrsN8kVk+ikvpEdPMUUUSbNAiXbl7avJuBBA5z5fxk/9ho39y5j5GABD2vzeLg/l4f78pjYV0S8uoJMzQao3YovU2zvVti7w5AmIOWoOm9ux1M0aOfL8OYOM7ckXyZRXczk3gLGdxUz+vpaxt/4AG79j0L/H8Gdk6AFX1m7F59qQH3zACJPzFaqFytagCThbhPR6h8xAHHrVpE9VE5sT5kJVjwrQLL71pKuX8+DvVtIHFZ29Fdh/ApMJMzWcvIPZT2ofJMBiHwSw7wWIIGcfEcGiFgnRikLIhtINxGeIIIoiaDQWMasGNTKQaVsWDVmBv1hO5z+PA8PfZwHNZuYrN1IbH8Vmeq1ULcdf8/zsOtV/F0fxNnzItmaNaRqy4gfWE+iZiPZ/etxqqvmSBvJ7txKdvc6MvuWkqhZSrxhHXdqvheuttjZKj2AAYPmQSatsDMC4R375T1+6eE7SbxsAleFkM3MvECiPlL8TJVGAuFlR8ok8ZHpxbn9RUZO/xhjJ/8eE43fxcO6l7i/bxOj1WuJ1a3Bb6yE42tIV6/A2bfMkLdvJX51oBkOlMEBTaSthF1L8WqeI1kfYeJohAfHl3P/2HpuH/448bZfhbO74e51u1+3wKx5PUWkg4Vj7/Fh3/Yw48eZb3Rhm4elrBYjiBTRu9dAouYzFiC1BTj1FcT3lpvADLs2wt71+Puq5kTim/SBDUzv20h0/wtwSnuu1MDEPTN3qTuysA3sYIFDKiUYFv35LgqEiPHwTY2lIIw7S2uE6tKGxkIG088Gxyrdu//3SDR8L8NvbuDhntWk6jbi12+GgxvgwEb8vZsMSLzdL+PsfYF0TRWJ2jXEa6sMZfdX4eyvtAB52rZ6vdUee6pI7c0nXrOC9LE13K7+EFzYA9H4jEulaTWl/tkZ1PfQM2/LDo9/aFfraalQnKnsJAnHrs03PyqzypTCCUJd6rZQQWu2lxtAD9z8czj728Ta/hX3Gz7D7eq/yZ3qVxk9sI3pQ+tIHV5Dur6EVF0+yZpckjX5ZA8U49aVwcE1UF2Jt7+CWG0po42rGWnZzlj/p5i69C9JXP0CRLshqRBwIE7VamCVGiSz/BlfhsH0nzFd5BrbyxspqjX892tIHPh+sgc249YWBQApMwAxvocBSGUAkKdrFb1M7Nlorh3bnUviwA4499swNWhuQjETC5AgvPgNAJGn8s5WRMSIEhMKCyWt1UIWHCrXrIJpGVw/Y2qymlTd7Ah+8gZMH+b+wU+QqN1MsuZF0vt34NSsw62pxN+/FqrXQfVGQ17NetyazWRqXiB14HmSB6tIHlqDW7sW74Co6m1bt2atud7bt2vN6j1qN+HUrCVzsIL08RLuHtjCaOMvwd0ztockQJgmyR0eRm+RNqkINrbwLPyh/g75TuVJVWjBqi3lJgWaI5BYxsWzCtrwpz42zGX2c7wNYwNw6yjZ83/B9On/xFjL5xg98c+41/ApHjR8jJGGv8FYwwcZa3iNcVH9Bxk/9D1EG/4xsaM/Q6Ll10gP/BHO1Wq7tcLUdUjIaQ2KgolHdE+iQIOa33+WDtClpJ3N9SQ0fbPxpX7CAuQBXPwTotWfNP4R9atNQCG2rwRqt8C+DbB/PdSshZqqp2/3byaz60VczYMdWkaqeinj1R+Bi182m+RIu92Pxon6Lqr270xmbPqBKS3rEc3Kong3gISdFhhkOkErD2xVjRgJN246wfrwStWYAO8q7tgBJgd/gYn6DWTqCnD2b8WpfhF3/6YAHAJIJdSsgQMVeLUVZGvXk6l5idSBl0geXEvqUBlu7ZoAGCFQHm8Ftnei7G519nrky6TqqsicLOZhXQXjDZ+BK/tgUqvbNGJavz3CpDOM1k+LO73A/Jorj6jrHgHEbjFtfkyTqmLIwC80bWDs6yfDuROda8ZH32mFT3oSErfsjrfRdpg+Qvbqn+Fc+zL+tS/CtS/Atd+Ha79r6eofwd39JgeMBwMwph2SMvam9NshKAJA6Oc0vtKidjZZUcm5v3SuwZveCCkz/l7wXM4wXPg9YjUfNRVdLEAKie8vhroNVoDOAEMgeUravxktmzA+Wl0O1D5H4kAVbudPwugpM5OvqKI2/jGRaPGBOt8YQFlSbuI9AEQjpo40QFJ+ihxxrfO9h8MYWSWhqbNlQ0tAph7AZD0T5/8frh1+nujhlbgHF+PuX4e7bwf+vu341QJJJf6BEqgrwj9YhFe3Gq92A86BHWRrt5M9WIlzsNx+iNxyWgAAIABJREFUXleJ9wRyDqzmSeTWrMZTuLNmrVG1ybqNOKdKGT9cyOjBD+F1fR7GtB2b/CsFGSZJ8ZCoP4JWnRkp9wwcolOtpp2xWiy36QsxvbhnFpMaHAS40TgJINNmpl+bwqiCvNXWnjbpEYWJgEpTl6bJToEzYZfpOqopO4HvTpF1EmZDmWzaMRntM4drvPSjgeYSKFRjK8U0CcZNa1cizg0keszw8ULNFMpbA5jsFTjz6yRrP0hS0bRDFcRri+xc0EFN7lbBgSr82so5ETVKen0Z9m2DmuVwKIfsoVwmG14mPvAbJsUGd1ZIVzyuLcudJI6XfU8r8iNGus0ARPlKIzgMGzLLddQLAocy47Sr6EQP8b7Pc+Poa9xtzCd1eAkcXAZyGvfLnHoeb/8WozG8ukL8Q3kBQKrwajcFtM4C4z0ARBrmSSStRE2ZAWNszwYSBy1Aoo25jNRUMnXkH8GNg5AYMdJEjnMKpSOMkxBoxDx6vmd46XQTCg9MDRPnEEOK9JkJENif0s/ZteTKIrabKkSJMUXMGIBy6xUWNqFJreEIuU9t+F4caC9kri0MKJCmIVKuqOZfdJ7Bls4xzyetoXI/KvIQI8UkCSMs5DPpgnN76dLKhlYxa7PMOdAguj1T8Do5iN/zOdIHXzKpNn5dGfHaAkPGfzqwZk7ACAHFgXVwQDlvyu3Kx9+/FL9+KWM1hYwc/bv4V/8bZIZnKQBFZWM4fswsNdbYvNsrYkSg6SOpW0VfBJAHRnuYkpZCnVFNHkzfhPN/wp2Df4fhA4VkmwvIHsrHqyvGq8vHqy3Fq9mIe2Ajbl0x7sFc/Pp8/EPlJmTJgW1QVwEHpWLLg/dr8A8+mdzaCp5EBiC1miRcS6x6PbH6KtInS4keWcF47UpGa1+CPjltKlOpNAPVhRKDxNEaZpM79W499I7fiwMlOZTNaplY2lYRIpn+0i6PAhzKeQu9dHW4zpVWGwm09YiJss3YR8pk0DWFlpCkyeV5aofXjLaHU4DACxxRa9EZ5jSo1Y3rBFWdUXBC46qJvOngnuzl3wOPPLEHZK4pwqm0DpNmMwMQDy8zZdKO0m0/TKZ+G87+CqgtJXEw35B3sAxqy22gQcGGuVDdWji0CQ5uxtldQWpXHv6hXBIHcxmv28B002fhYYOZ95GNZarSe6rTr37ROAWq9YlPqF1u1aPGvLILi6yJpTmDQLJIa5g9z4fh0k4mjv4YD/dvJ3E4F5oEDqnIdVZLHMpDD+4cKsOpV0ivALe+HP+gkL4NDmyGulI4mA91AUgOVrwjQIxpJvPsbUiShAPrze/L6Y83VBI/WkyscQWx+kVM1FUwffKfw/B+8GQ6iv0yaJcpMYZjp7vfoXve7St1tFIVVSvLmlSKlivmod+ypL4ctyWQjFEVLJZWv2vQXG31NULWH8fxdJ1gIZRSVVRqXNmgIam0p8iohwwyxaQTQs2T9rWKzsNxHLOXeNrXdpcqxyRgKEQvsMjcnLm5Z9KgFiBBxUbFdmcAksVT5GzsKNMnvx+ncaPxQ2Vyi3mTh1aZ3DAOCiASmHMFSAXUr4H6dXj7NpLctcYIaw4Xkj5YxKiiWmd/C8aVOTBNwneY9jX6Fhi++PpdJETESixZw7bOklSmBtYkmylOrm18YsMwXM10288b2z7VsA4aC6FOam0HXs2Lxodw6nNxGueTPTKfbEMe2UOrceu24tdug9qNIMRLatQWQ22eBcrBclxFs55AzsHVPIkETmoEuk1kG9cSP1LK1KE84oeX4xxdQOpIIQ/qP0ri7Bcg8cDIApkk0pMaXLNB57t00DtDRKiQJpBmUB+K9F5kxH3wffDeJNAFzKnTgnXT0jTqcwk0Mbg2qElnYmTMfoCPrqfUEOEqBJ/RFvoj9CNVFE9FGHx5M3ESZvmrZmVmfFOrNnQ74a3q/Dm+LEDSpPwk2cCn0z2ZxVyJh/j3DzF65JM4R6qMteDVFBpwpBpW4R4shEMSls8AEAMwCdtSOLQDr+5F3AProaES6guJ7i8n3vSPyF79Y9zUJZR4orCvFLIBhgSQ1Q5P7IGIzaGRhLOTPDpZp5n13Or41Bjc3k+i++eZOPZxEkd34BxbS7ZhJXHlPx3YbgDi1FXh1OeRPTLPkgBysAq3bpsh/+BajMSQ31BbasBlNIkBSEUAkG9sLTjKA5A83kqrULsODm3AO1ZF8shqJmuKiB/Kh5OL8JpWcL9uPZMdPwsT/Qb1inzLsJEv4D1m2AfqVoB5K5lONGp2piPDQ+wH4jJBT9pEqyHU6u9gSwIdPDv5U1wUAEQ8rbQIs2RZZpmksOeazUMdXwaU9vASqWio/tnx0TjJjDNRGXn8Kd9qGhNREUDSZgY5hK05XvehC+iPbwJALJ95qJBENp0x2knmi5ZQuLHbcGcfIw0fgSMSjJX4e0vJ1JWQqi8kVZ9PtrHImN/+IQuSp20NPx1YhX+gAI6+CMc/aMx7o5GOFuDUrWKiYQuJgZ/FGzthxkQjpa4y5rUZUv1n1wBJAIVkgaP9QdwL4N03kkn9LItapL1nTOdPNOIP/hzRxh1m0so7+SLJk5t5cHIZd48uJN24Gk8MWl+J11CGd7jAkt7rs0PrLdUL1astqUPqywKqwGuowKtfPYe2DBoKoKEEt76KbP0WMod2kG1YT/bYQjInIsRPFDJxXFt3/RkkboIW9gdCdzKrFGhxipg5ULe2v6ykNe8FHKlSda3pUYMfKylDDa3P9b06LaTg+BBJT2hnO/LhIRZ04Y2Eg/Z4oqh+X8eb/3SoOXn2OXYBmO5CNHP8o0NmfWh/8an/12+q+0yKm2z7MaLcI+3fhvR1HrT/LtOHP2yiV1RvsNGmA9vM+ERPFDB9MpdsY4kZd/GG+OBpWuor4FCZvf6hqhleM583LsM9ugSvpYzx4x/GH/oSxIcgOYyTiptKPNFE0G3BpkrihTAlySwBIU3ELJF1Y6YCRMyz4FDI0Umrds8AXPk8tH836YNL4NBiOLKZ5PGtPGjK5cGp5WSOluI3rJk7HV6NP1dqLIYjK/AbC/AaNuIdegHn0Es4DRtxji0ne2IBiWPLiB/fQbrj5+DmPltWx1UMHKKeCg1I6UokBAAJOT/g70c5ajJ1JH5tp4aHGSZ9as76DjlBYAtki8cUSYZJowW3Kit0nJHWf0288RU4pIRJpZVshwPbcQ5vYPJUIZPNeZZ/5jj+NJRDQymmrV+L3yBSmk4x/tHleMeW4p0sJN30Aqn2H4crfwqxQcjGSacgqjVVZjwVvbVmaTj/p4CKQBIxYy7fL6mCW5YFHH8YEtUw/pskWz9K9nAZ1ETMRIx1qDYYcyZ1fA1O4zOAQw9jOqcc//AcSB0RAqR+qwWIwCGt1liKc6SYeH0BiRObud/wYaZO/yKkZGrFSCWSJnPK5mfJeQ0UxGMiV3+IA2ymqhWXdnLNdux3CKPP9TFkqpj6COqTSZL+/UCI3CF2/Q8Ybf00ySNbLUBq1oGobi1OYznRk8VMNRWSlYCdy9gfLofDxXA4DznlHLIpTv7hUrwjefhH8gwPZA9vxm1+jQdHNnO/9R+Zbau1dimbcEwdcw28xlK+t5YxK/iufwqLi8x6EBN5kWUQ6uJUL/7Ir+Fe/hST9ZW4tQVQuxRqta5Ys+Mb4dB6aNxgESsmD5n9ads5do7pVAOQPPzGQryGDTgNmw1gDUAa1uEcXke8roTEkUruH67iYcvfgzt/AdnL4GgpsawMJRfK1LKZy+E8hkWMNIY0jAASgkQdJdH51y8xlqpqJh2bnJlOaxJTxfmGGOn/UUabt5I5oiiTQvqiUuM8e0cKiZ8oJnailOyROQjGkGdkQTSugsY8oz28hnV4jeV44gsB5fBa3MPbcI5v537jSm4c3Ub6whdtpRhV59dgy4IOMtY1stYHF1gUrPKIRLlPQkvtLYxAD/mwlvTQDzPduo2E0tYP7oD656FuG+zfDvuVyr4eDlaCNMiRCvy5tjr3SNmcicYyOFKCf6QE92gJ7pE1uI3r8Ru24TdsIXmwlOThIlKtFUy2v8h474/C2C6zTUJoVdn5ChsMmq1AbM0s63Q+8s6kUWRu6ci/2kDRVECcaSY91X1Ut2gtfBRGD/Kg5UNMnVqFe7QIDhdBQyE05MORlfjHckkfLzOJpe4zjL/GnSOFcCQXjq3AP1qIf3ijGXsatsDh9XBsDenGQmInyhk9uZV77Z+G+18CX0JSmylZB01NCBALEssPkYdcYJrbJlpialqNNeFc+vdEOz7CZGMp2cMb4ejLcOQDcPAFqN0OhzbbUJom/BpD5g4Z/Wnb8Py5tBVwuMoA1D2+EufECpxjZThH1hvJIYBogU5aczany0h2r+P28RdJX/lVu5FmQuvtbUc8Aomteh7+bftPjrK80TCEIa2iCNU3IV/821gRaeJ1iklGmcTsMSQOmxyAi/+esRNVJE8shKO50JgPjSuNv2gY+ViuHaejFbhH5zLu4TkCSBEcXYl/IgfxgNu4EbfhRfz6HdCwEY7bbA+/ZS2pjm3cPL6O6NA/hWSdWQVrXIxZ4XaBwwQFA20SGeE8ca7hch9nopn4lV9lsvtjTDVVkjieS+p4Hl5TKeljVcTq15I6vBZOrYNTRbhHlsOxYjhaCkfL59jq3DnSkUo4vBWOrMM7uRS3aRHuiSLco2vxjmyynzeU4B/Nh5Z8Uq0FPDhRznjH98L1P4eoainZ2sICgt3yTHudaDsHK1FCoEhaKnxpTS2p578GiGbRJ5hmTCaqOEuK9eGfE2/7hNEQcpQ5mmfp+HI4sRKOFbwNz8xx/MV75nqr8E6swj1RgHusEq9RAvwFOLwJGpfhH1sEp8rJNK/l4ckiRjtewb/xKyYbnawmZAMtEqxAFEBCikS5RUZrE9whssP/i8nuTzF2tJh4YwE0lxA/lkPs5BLGGldy9+AqJo8V4Xeuga5csicW4R2f9cAhWN5rO1dghOeFAGncYDuoaRFOkzRJEd7R1SBqLIKThWQOLyJ+dAmp1jU8PPYSMc2NxNpmOkeTXjaLQLPOsRl1GwJFALKhP4FExQCCGXGZpn9FX7LTJ0iaYnFW7I7BvX/DpMyeYyU2BG8kfAHeiZW4J1fhHRMYVsORUjgSCte5AqQIjq2C46vwjhfhHi+1dGw13pEN0LgWrYOnKRfv6ApSR1eRbClnpKmKye6PwvgfgDKOBRAZA8EiwVCLCCSRTDZqioulbuxntOVzJJtfhpMlODUqCFBEtG4BY4efY+T4Ukab8phoKSTenofTtRg6l+E15eKfKMY/XvK2LSdKzfXettV3z0LHK+HIFji6BY5X4jcV4LUuNERTnr22BuJoARxfin8yl8zJKmInX2Sy6XsYPqnatNfMwiY/JSfclkBS/ELLUdVRIoHEmlryOYI5Eb0VfYcDJJlM4rrGw5gRA0plUbE59Uk438h0FG7W4PR+F7GGCN6BFXB0HWgW/dhqOzanivCPr4Nj66zFIRAdfxYeKIETeXCyAP9EFd7JKmPteKfyMON/UsK7HATKk0vh1EqyJzcRP7WFyY4S7rV/GGInbE2xVAIv7ZqJWo23lOG0r1ysWILszS7GOn6V0caPkT2sybw8qF8LTdugZQ20l5LtLCPRUUa8o5hE6yrSzYtwTi0OAFJowXHiG1uBjZOS4m/X6rOA3glIOubtvj8hLbEBjm6CYxvwmkpw2ubjtEfwmxcbyYGcRCPFVhnV7h3bSPbEVuLN6xhp+Qjc/e8Q7wHtXJuJ4SY8m2wYzLiGGkSmlmETASLAyaPZtxne+Y57k1UF+VkvgSOVSpHJZMxkm9GsWpE60YV76TdJd1bhHo9Ag6JLSknaEoxNqVmK4J3YYAEipj1WBCeeYfwNXxSYa4QA0XIHp2UlfstCaM6xADy22gLpRAH+8U2kT1UR75rHWOdquP3FIMviAXhR9LwSjgKIwB9h/C7x7v/O2PHvMrOOnFA4Ls+mghypgJPr4dQGaN0E7evw2yugvQRayuCUkFlkpIPfNJdW54RUErx/760BzbEqK6mOS3qU4LTm4LRF8Noi0LwQjss5FEgqbMqDgHSykmzLSqbaS7nb8Qmc2/8Zkn2QiJuisr7WUwWJd9bcUgasXU6qyKARnValfMdrkFnYMFojnU4jraLWJHuqH5K38O/9IdG+v028qQhOSVrLzKqAxu2g9KSmSpymciPlpe2NVDcAeYbxF0CkgY6X4mvsT5WSPbXaZJmLB/zWCDTJTy4H45NughOr8ZpXku6MMNWZS7Tvx+HO18HrM9u5+dkJ4umMqYov6yHC6HmiLb/JyPHV0LMYWjT5kgtHFkDjAlAlioPFpOvLSB8pIXN8hbH3OVYGRyugqdR2hjpkTlQMp+ZI+u3ja+DYWjhRgd9cjNu6Cqd9MW5HBNrmQdMSOFYIjZq3kaapNOrXb1tAqnMxd04UMNb1d+HG/4DoDSs2BBAzy6p1G9q9V6T3wfJSM2nyV8PECgGi7dlkakmDhCaWieIlJ01KefLSZxlrryB6LA9OFUCr+KECjm6DYy/gN63DbS6DpjI4KbOq2FLTHMdePKPxP1Fh6VQxbnMxmZZSMq35OO0L8NvnQctiOKmMi+ct6bdbF+F2Rkh0LmOi9WOkz/0bmHzd1ghQqkx6ykasDUCifcT6/h13W9cy0TmPZPNyaFkCp8VgEWhZhH8qzyDUbcrHPbUQ9+RCM/egORBOlUFLwZOpOR/eieYEqgCM6tzjZdb8kt3ZnIfTIhVbGHRQBP/UAjiuUKMiGpIgCj4shrbncDqeI9a8gPGmtaS7fgzu7oLkHe1nYBas+07UOO42/UCTR3Yy0ZhYf0V8kLCwtVqB5LGXKqmPt8Dl32SyZzvjrYtJyKIwTFgIHRqbdXBiI37TGiPANEacWgUnCi3jPuv4Gx9WwKvAbS4l07aCdMcy0vKTW/OgdbH9vaObQdSkiOYi/LbnSLevINYmf+Rv41xWTed9wEV8Z8xsnaDxjpC+Cnd3M33lJ5m88Alig99Dov9lol1FjJzIIdO5AbdtB27LDvzW9fgdi6H9OWjRepBiKykkLZ5E7wQefddcNHc6Jd9GpOvkGpC6LavJtpbjti/Ha8+xdujJXDhaaemkgCSALIT2+dC6ALelkHTLh/H6fgZG3gDnnNlsJjl536TFS3M8CveGVpU+lX0upHznvkKN8VZH3Txx5oZZJ+/2fpqp9nyi7QtJN5eQPVlmwdBRbiKhSHM0yyzPh9YlVgCfyoemkrmPvfjmlPwXgbAcmlbjtZSQ6VxKunM5mbYysq1l0Cq+yIWT5ZbEJ61LoXUlbls+XncZE80bmOz6Xrj/e+B2KlZt19QYJ13FAlLjuNNncSaPQ3QPzv0vMXH+3zLe86+Y6vgcsbafJtn8z0m3fJxM1woy3REyHRGy0jDtK6BVKvUJpE55Ij0jQKSZZO/KzhRYTpXjtpTbzmkrwW0rwD+10n5/cjmcXAUGIOqkJQFp0EqMepY0yV74LEx+GZIDZKeUOvFoD0aBRGkpZnvrmXV8Asp37is0q6RBwpc+m5qaInG/iWj3D+C0VxqJnWpbbswbmTlO8xoj0WlbDm3q65XQovcSSvOtQNOYPZOAVPBGjC8AFuC15ZLpyCfZWUC6XQCRv1EZgFPAXGjvwQjmcgMoTq8g1Z7PWPsHmTr3L2F8f1CIW7V9IaI1I1pPnFbRQVMoSTVWr4FzEbyLMNIM9w7BzTfg8m+RufgPiJ17kYnezYx3bCTd+jJOy6s4LS/itm7DbduI37YaX458Rz62g4TYgNRJLeqs3MD0eitIZLIV4bWtxGtbjteabx7EPuhqa8pJKrQKeJIOS+CUACJptBq3tYxsW4mRHnrvyR4WSKQ1TikmLpNPYNY9rIQuResK8ZoWku5YQqy3itjQ98OD/2krhodhLNXaDXK3lOCoORNVC58Jos947gJMSKEdFrLWW9vw+0fM99YjvvFvHTv7+sERb7F+vvG8Wcfp2JCMFgwnPYPU/mBdhCZHwyW11gOTxozhJm8yMdzC5MUv8PDoFtzWZdBZQKYtj3RrLm5HCdmWSpInCvDalwSaejm0CiALLZnx19iHJLBIy4iK8FpFBUbKu225hvnFC9ac17EKEgXgMD7PcmM1CCDpjiIyhgfK8Zqr7LHmd2X5iBdK4FQVXrP4NA+vp5ypzud50PV9pG79PtBrsibcdErp7rM6y3SyOkFBrqQtja9dUc1S0HG0nx3eADgdkGmD1Ammu3+HVOevkez4HIn2Hyba/kmibS8Saysn0bYMvzcHTs+DLmkbRZbmwcn5cCwHjkj654LUrbRBSwlKCXAUVj49n2xPhGRbDpm2cpyWl8k0bSPVtIx0i663AnpLwNiZYvhi/NZSQ15bMV6bfe+3hWZgqOH0d/CZAhIKNhzXdZZC53y8vgWk+0pJnP4E453K/r0KsYytjKCZI8OeWr6kPKQkqewkjjONp6WyBjBxfD+K40Uxc0yGmR9lAAdsOhMrDhfoaKJy9lA89kf4hTHnwvFREFKMHVxKuAmPe1Ib4nF2kCGtPdqDfdqVm5SeJp0cIZoeYcofNxOBYyZbz8wMmN3DmK4hdeHfMNr0UTJtimzm4bcJDCEVojHw2wrx21fhy8poywtoFbSJgvFoXmV8RxMRba7Ab60w45/pLCTVvYrk6aUkexaTOr2ITPdSnI5VZmy9lg34LeusCdW2xJjTbscSAxIDKAnW1gBIBnShQC2E5lJoroDmdbintnGvbjX3jlYy2vMhRs78E+LDvwsZ1TEYeRuAPKFzTeKjQp8qjZX2SKdc/MQUZJWuMQSJdhivgTtfxr/6a2Qv/ATZc/+QB03PM9a0jqlTFSSay0g3y4kuNSFlMTRdq/E6y030IXGqmERTKanWPLI9C/AGFpLpWoXftQE6PoDb+hLptkJSbYtwupbC6VVmYASCuRD6fWO/llrV27nQBid6l+L2rCfd9Sm48QV4cBQS9yFjCiqZ6Q8rQlwyaKGQdiHRbubSKAk8L2FLkqrqvUkPDpg3QIedtbf1qbRG3G4oGWiRsP9DZp7dmu/0gUAi1faWRV76Ssc8FkV4y0rJ8HohSJJBKSEJQbN92SiOPxqUBkrywFHdSNcsozXrPKL7cK/8IomeD5HUOLYXBmNQ8NStAY20T+uKwDKwgi3bUUyqq4Dk6RUGHMmeBaR6FpDpXozTucIAT/NzApPAkO1YOousJnHb5WMoB68YTpdCt3itFDpk2ZSYuT3a1kLXazjN20l2ljPds5oH3duZOP9ZmPg6+L08vj/II/H2De9kXphCG9peN+uS0QaJaS3JUpEBbUg/aXdl1TpqLdNNaOuvq7ao2d1quPUVvKufJzX0fxEd/D7G+j7CWM8Oome2MN27jrG29Yw2lTHZstSEX+nLh4FKaFday0Y4vRm6NuO0bTKZuYnOJWROL8KXGddeNDdqk6ottoMjqdaeCx1F0FmB172WdO9Wov0fxLn+4zD9v8A7axfOyMIxeTvSIirZM2FaUw5ADKjvQ69erfg5OEcdqzRqFQ5QqoYFR3hAwMxvZeKQmdXqOuHfBhCBRjG5YdIooU04u9Uxb0M6X1pR92h8qmEy3CLBXVOlS1eQTDC/qe2nJ0+QvfILTHa/xlR7LunORfid6rP8OZLOlXmWAxJOXTn4nctxO3NxO/Mtda00n9G5HDpWgpjemNgy11YabZPqqCDVWUqqU8DKM0I1073MaJx01xIe0VLrQ3etItOVZzQe/VXQVwI9EdLdEaY7lzLR/Tzu5Z+H+J+/O0AEjJBCgGgPakfFBVzHbHWVcFLGoTECVuMQMofpYY2N6uA8hPQgJI5A9HX86S/jTf4W0Zs/TvTqP2bq/A8x2fdJpk9vJdFdQbZD4FhrHT1FyLoK8bvKcNu3km7fQrxbEmaZ6UTaCwOAzKHVtY26z8NeZzV0VOJ1VZDpLWaqbwWT59YRv/YDMPoFSPWCmEUZJ1qVSNqYIZOoBI9vhIhhKPVByKN6L0YTQwZvw69kYs0s6Q21TQgQtSEYZrch0+ozk1EcACNYjz5jIpu5YJliYUJIYDrPmNCPcmm0Pj/JQ6a4yzSjpsCBWQKh8Uw8hFvVpPp/gWjnh4h2FpLuysE5LYZeOUdw5Btw6Xy/axm+wBEAxABOQk8CrK3IRkhbQodeJpL8xxzr/LeXmCCB07Eap6MCp7MEp6sQpyufbHcusZYc4go/ty0h2b6UlELAinLJMjGgWwYdEdxmmfMR3IEI8Z4iJrv+Jt7Fn353gMzUGnjrxlOqwOFbASTrW6TiZSFpd1UzZZ/FgEemmeeEeymo5pO83jH8dDskD8LUXnjwP+Dar+Ke/Qzprg+Sbi0j0zwfpyVCtjWC07aEbMdqMt2bSfZUkTxdjttVbBxEOiX5C3jqVuAyWiiUgrpeMV5XAU7PCtKDOUwN5jAyWMjEhe8iO/xvYbIBEhNGEIj39cyBR2Aqk5jl66GgCJk5ZPqA58OPH/Mhws42TC/zaRbjP/Ze380qHxSCT79hflzw0x3J5HvkG1ng6MZ0QmCO6TIKZHqPjtaZGipzmPacvPtnuAN/n2RrCamWZZaxThfA6aDPu/JgDmT6uLsUp6sct7PcmNq0r4Y2BWPWQnOQOd6kQMoaE8o1Gl9zKc2Knsq3CfwZ+Zptpfbc1rXQKv8kIJlSum57CX5HIZ78mI4VZsrCO6G5sgiJpgjxtgjZMxGifUsZ73wJZ+gH3h0g0haimbELNEooCbWb6Zg/kwQeBD89s/zd1uNQ7SbPTN0nHEhqP/UEJGKgTUgd1XkyVUDugXcJEi0w8jrc/E9w9V8YU8fpXkCyPUKiPUK6vYRM90bSfevJ9K3F7Q6BIXA8JWlQu1daEsA6iq0W6cjF61xKtlt+0HxSg88xPfgco70FjPZ+F6kLKox9GOIjNgYc+g1GSfhknCzxRIppVZcPlnTObi13iptnuQvSBobpW/u1AAAgAElEQVTBw0iSmFwSX+wqCqW/PhdApHmCc2bODZjecLaAIAqON5GpxwMBOl3Va6TgtUZf1T5mLC79XvYc2cu/Ded/EPrXQvcC6BDlQFe+te3nAIwQTJ7ModMFZE4X48gX7VDe3xpoXWNzAAWQpg3QpOUVa6BZ5rAm/wSMFdAus2uJpfaV0C5zW2NYZq/TVgkdG6FjA7Svx2+rxGkuI3WqhGRTEfGTinZuxu3cQra3nNRgKfGBKsb7XyN16Sdg/D+/O0A0UaS4dzijOns2VR0cDqM6Vqu8tVN2nAfEuE2Cm6S4Tdps7jhhlLhklzHZxAeu3Wdc+1QYZ1bF0hRvFnomJmCyBy7+PAy9QmZgAfFuAaSMbNdG3L5S/L58/O58mCudXgH986FP6l3Om6RMkYm6eJ0RXEXe+nLw+paT6VtJ7HQhk53rifV+DIZ+Dq5+Be6dhrG7kBizRd/MRpEJprwkDzOquWs1jPJ6JArUZ9Zx12KtoPxpaD4ZgIQH6Q91jCgAkzk3+D441jr5ykLW/Iwt56/fMBQIs3AjJNO+xWrzFVTw0wYoRvkId6lpstNv4D78Wcb7N+D0F0LfGji9Gjplii4BZXP3LA8ETC50Pz35PcvIDkQMub0r8but9raCShpB0UUBpgI6ZGYvg57n8PsieL05NkLasxB65sPpoO3VeNoxpW8x9OVCfwl+/zr8/m3Q9xp+/3dB/8dxej8DF34Xd+jLcPO/woMvkb31X0nf/EtTYhfn3nsHSAgSI/Vm/acCcyILHMFFal2p45pPuYNnViuqHcFjHOkWVQT0Xc9YWcbq0vyC4QchJli4p+IYIknqG79AamgLsf4ckt0FuKfL8HuKoEca4OkHJjxHA8Tgc/j98w3QvM5S/I4AIB3zcZXL02s1TLYzD6e7FG9gLe7AJjI9zxNt+YTdj+LqmzB2DNyztqIHWnSl1XYm99HssiugCCTCgl0LHdQoDRjdcrTtWBvynV3uZ5Yror4K+svCR9saq2qkStbY2YoQVo8BIzxvFkCM/2PGSoWwo5CagOlrZO/tYfziP+Nezxrigwtx+iK2n00EqBDkd3QrfC9aMecx8HtW4PblkO1fhNe7BL9nCfSE11WrlKcV+KdzcXsKSfWWEOtbw1R/FRP9m5ns20ayZysp0entJHu2E+/ZQaz3RaZ7X2Gq50Okzv0d0kM/gHv5x+DmL8Dd34SRL8DEV2ByP4xfIHvnEkQvgn/Njp+CTupETRTO4vU5vBUyZMTOIv09Q2FUJTQVQps4XLoqyRdIOyP9BLBAaEolhYffbyZ55WeZPqsiYItwJSVkTyoPTCZWz6q5Ue9y/L7F+P05RlPQuxxkW0ubGCqC7lXQLSCWQPdq6KrE75FEkgRbSeJUFdnOT8LQ5+D+VyDeaje1N7UxrPYI/TOjZV3XhMiduEs2ljUVFNPOFBlPJULF6KpwKVJwVaVoRCqXak2gpI8xV5Ne0JpAlN0YT6asjpMuMUVrfG2HbPfsMAWmFa71M2Qczd/ESKfDQndX7bzWw68Qv/gjTPR+gMmuzcS7V5s5oWz/KpyBHDzzzHm2j06vhNPqrzn2vcasu5xsy3YTmfT7lsPZCJyP4A3KUY4w2RkhdSFC8sJSYhe3Ebv4aaYv/Sumr/4Hpm7+B6K3fpvYtf9C4voXyd7+U3iwEyZk+nZCesguqXVGzF4hpjq+CnVoBaFK+GjORwWFJbFMirYV7D7jQSEP64c9I0AEs3BCUVPy+kFbKcIgcLbpICfG2MQCi25GIAm26TXhTlUWETPYpEBpFqPydfhkGu/OHuKX/qlxmJNKpOyQk7jeDpak/BzJ712FGRxjaklNSzqWQKfs10roEkgEkIKABMjlMBCx1CtToxS371WcMz+Ie+XX4OHXINkO/k18Rs0KxaSXJOlmTd1ps/4o0BxZL0nW1NC1GyGEhctsETNVXFHFS81oPwqKGbAEGkmgC0ldpe8eeR2BSacKHdkkmeQkWWkJV7pNY3AP6IP4Trw7nyd1/h+QHqjC61sJfUUwUIHTU066v4jk2RxSZxeSHViO17fKAuNZwBEAhK4PQOfL+D0FeAPzcM5FSJ2PED0zj9GBFSRvvED85qeJ3/4lUvf/B9mxo/iJPvDOABfsgjd3GNwR+1wh0wcaYCaiqh0lAtktv8vUT9beQmHcyFS/j5tKxyr7E/Zx5Bsmld46yfSOf+suQi9Erf7WyIcOp1UP8jmkKozvEah4fWTUh0BkTpF5oOrrsrJkuz8we1joigZX02M4t/6EyfNVTPVG8HsXwflSAwwx+JxI4JA2kLlm7NWF0KsJSGmRSujURFJpICVzQJqrV8eEtNisrNQMb6p7Gan+IjLnN+Fc+wT+7Z/CHf7PkD4JqSugOSP5zDJJg6Wd5tlCFaruMCnlvgmfy9FPOtrfS7P2tuC2ClUn3/Jv0plmyomZIngJ3xZTNf2tPhUJWWHgylTxiEL6ISRuQ6KD2J3PE7v+A8TOvkqmrwp61tgMhe4VZl5C/ldqYBWxMwXEzq4ieXYx2QEJBYEkz7TSpHMhc43+EhhcA4MbcPrKiPYuY2KwgOjlV0ne+imI1sPEdZiSbyrhK6tDGla1q4JAhfrQc021+2wmTiodJZGeJpqaCjYLst0gDn0raQysHBf/2cqKj8xVlR41vRj25tO2spPtTHCYKhEqDdMGdm94E2pnkwFJeEJQh0gAiZJkmltEGTaAMbeoJxs5TfL6DzN1tojU4AI4vwA0WP3LoF8O91O2koS9hdBTDL35oL/NZ7n2MzMLq+/0uX7nORiYB/0LoHeFOTbVtYBk7zwy/RGcs/Pwzi3COZtHZnAj8b6Pw93fgIf/G6ZaIH0zcOS1eUvW1OD1ZDNJBejBxcxhZwVDoWohUspWfEibqD69FnBpjYpMMn1jB9lEGnWNUEmbCIFCh5q3eQDuZUi2wsguYtf+iPGhX+Th4HczMbiGeO9yXK0HklaQ+dS1yKTe+P0ryAzkkzhTSvxsMalzS3DOLLL9HfbXXNv+JXjdETi3DC5WkT2zgdHTVYye+QjZe78M6Xq7kWKgIhXpVoFvdVnMc4m5jonAKZ9Q2M9mfLPSMZNNkHaiyHQN657ZfrLWibpodldbGaUIn0o8CYA2amgrKz4DQGzKxONMbwAgtRXSrJvRoiO7tkKFEe6ZTTWN3hNIBKYA4eoPYVll/RNmB4yslYKxEbMpZOrazzBxMY/xM2LK56B/SQCOubSLoE+OpsKYMtnKLEgGnoPBSHBtgUHREIFQQFF0ZAX+wDK8C4twLi4ge24h7uCSQJLmQW8xfs8asn1byJ79CM7lz+Ld/XUY/7pNy3HugqJ2GqnZYi3U7eFnihQnbAVDL+0bU0m5X9o2IasJSwFJnR5eR+CwHWjb2ChM9cCD1+H2b5C69hmmL36IyaF1TA+VkDxbQuZMAU7vIrPKLq3VmFps1rsAzhZBr8zHMpz+YgMUZyAXd2AZDEg4LXjUP6Zv1D9PQQOLyZ6O4A5GyAxFSFwoIXrxk2Tu/DokjoP/wFTz1opeJ4UpF6qa0Yp6ahMgU+ZUyHgrxxsmnFENto8MCtRZYehbroFsrVC6BBZN+L2ZdFXp0W8FQGZpCv1+KOGsWpR61IYuD5BDZMwsHSB//y1jLR4xm904U2aDeFIqqHoPRvYyeePT3DuziszZlTCwdI60BAYWghzEnnLoqYRe2d5LrcMop3FwCd5gLt5AkSEGVsLgUhhcjndmCdmhRTiXFsOlfLhQCufLYKDISGLNEDunl5DoXs5EVyljp19kcvAfkrr6y3D/yza12u8B9xw4lyGj4toPQflRiRTE3EfgERNkpU60h7N8Ny17jEImjukXTS5pdZ9209I+h8mzkFQm9p/DzX9n0vhj/a8x1VNMtH8B6XMRGFK4VH2QB2dXwJnnyPZFSPdE8Pol2eXbCSRltu0rAFH/SnMsZ2z/mD5RvzwtDS6BcxHivRHGTkeIDr0AD38dsifBVdjcagWlnaeUca6ijYGbq02BTJhTfaF+MTRr7/JQwDwGFplockQUPAoA8tj3gVkq4ATHRd5G/s9i7/DsJ7UhGnU3eh8au0Jq8LL6y3L/W9+H0k+XD7SIjb9oNyYb01fJRy+TxpeZoH23tVdf7AqJe/uYvvxLJBXbVkfPhfqXW80gp3Qgx4R8zaCfmR8AYyXeQB7uQBHuQImlwQLcMyvxzi7EPbuQZJ9MkGI4VwEXVsOFcjhTjNujXKXlMFiC119CuqeIeHehSWNI9pfinFtL8uJ2Jm/8LcZv/xDT93+S9Oj/B9NfhMROSJ+ATD8412xCaHYEU9hPrcwlkXcrAFcbJPeTnfxjEg9+hanhzzJ57buZurKVyaFyEufzyJ5bhX9mFQzkQ48icuUm58wsk+4shDOFcGkV/pUcspeso5wxgQgFLpbbYEWnzivARPsG50PQTwwoaDEHOpODfz5CvC+HidOvkLn4CzDRaKteah2OapYZ5ah6AFpeoK0lFPtXHyjJUoEGmUWWFMOTESVBrKkEV6onVABv5T39Lf4LNUjY6jOT8mN5O9Aguo2QW5+21U1Ir4tC2M4Cy+z8ovAm1M7GXPi5btpcR4FRXctmz5pGE4jZuO21dJLM5D0y9w8x1vd9JAfXkRkswT2z3A7aGZlHOVYTDIpJl+KdEc0C0oDMseXQK6koiRh5pDXOKtS43IJDgAgoa9o88zvuufkGIJwXcFS1cRVRrSfpzCGl+ZUzBTBURqYnD29A70vgSjFcWW4kt8yK6b4Ik5dzGL2Sz/iVtUxce4mpqx8nevUHiV/5KWKXfxnvzn/Bu/0l3Nt/gnvrT8ne/jMyt//MhDWzw3/M9LXfYPL6zzNx7UcYu/JJRi5t4eHFlYwMqdxAhNGBCNGBiIkOcUFh1FwYkLbcAF3roXuNiQhmOpeQ6FtI9sIS3GuL8a9H4FLE9ouWLGi+qUuRw1zokwZdaISE6degj42Qmq3N1e/qx8GVVgsP6rdX2n7vk+ZaTrwvzwQI0hc/B7e/DmMXIWHNJpM5bgAi01xb1N0K9pdX1oXdnFOTnOH+KWFrLRWBJvSPQ/4OzKgQLGL1t5LhQZkzOkfFq81LR+k1l1bnhNz+1l8L7CZdOryp2a0On/23uQd7YzN3Hn4fPokBXPgAw8Qe/jfunP8h7g++SOJSMdmhYGCv5sKFIvzBfOM0Z8+tIHt+Kd65pXBGJlng0A/KtJBJtQDOzTetf24R/tml+GeXPUbezN9Lsccstt+fWYEvmvl+1nmPfW7Ps781D//8PJyh+WSHFpAdWkxmaBmZ83lkzhaTOVNBZnAdqcGNpAY3kxrcSmpgu6HkYNhuJXlmM/Gz60meW0PyfCmpoVVkhhaTvTCf7IUIzoUI3lDESGr7fIvs8+q5B6VRVoHpg2Wmb7xzi3HOL8I7vwDf9IeOXwyDmlQNyPTXYnO8NJP61j+72PbhwCIQnVEfLsYZWk7qfB6pc6U4Z8vgrLSVwsjSTCXcaf0oYxd/Bab2WG2onXy1D6MsoWCLd+tiaApAQQlpEjnRllcfTarKyVbQSK2lGR6a4WvDYI/+C3krbB99M4OcZ5wHeeyK78Mfk2TSzTy8818YufpZoldfJHrWJpxxYQWcL8Y7U0j2bKFhnNTQMpzzGkgNYuC3nBWTv090TqCcZ+xw2eJzITGxf07MPFeyjDyXPpDAyJ7LI3s23wgII2gGF4EijGd1P4vInFtC4twK4mfzyZ4rsZpUWqx/vqm1Nn7mXzI9/HVIdmH3qlG6keVPhaslLi1ANBckTaKoXbBNYCBfv5WM920OEEmSGzjJg2Qe/g7pW59lerCS6e75NtJyvgD3bBHOuRLSQ/lkLyzHHVpow8NnckB0LgfOv1+ke3nOzB7PrdW5CnfrOnOlZ3j2czJp7YSiWbszKA2x/LE+VUg4O5hDdnAhvo6/WAgX8412muqvxB/5HfyYIlZK9VAoOmXTxGUkBJFNa5/IDxE47D6Nssol+L/Vr29zgMjXUSRMdmsjjH2BzOVPm5VhSUWmhlbinCsykit7vojs0ErcC2IoSevn4OxCOCfGegYmeaZz9du6HzH6XCiYC5ozOJ7x2c/Jj5A2CEAyWIF7Lh/3/DLcoRz8oQX4Z+bBWaslvbPPkT6zgtT5CjJXXiB54zPgVQPnbA6UP24mVJ1k1gaRAh9aGiPc0MZuSRGA4/8HhHybA0TLSpQHFofMXRvWfPgfyVz4W8QHC3AuLsW5UIBzvtSQO7QKLs7DOqvz4Px8OL8ILryPJI32rHRhIcyZnuHZBUwBQNGsc4vh/AqcoWIyFwpxLy6Ciza3yrSXrB80PbiUiaEPkb3972HyEDAUVBEZA2cSJxkjGU+YZd2O6xt/QuB45HAHfu3b+g3ffH3ybQ0Q9VEyyBq3AbQHkKiD4Z8mfqGM9JX5ZC6uMoMmkLhDeXbQNHBy5gUQMef7CpBFAUDm2M4ZGCGongEgQ4H/pPki9eeF+TgXVpG5mGcBoiiY+vpqBK5F8C+tJHbhg8Su/zKMd9mJUi3ZVl6eF8XNREmnEqb2bzqbQbvnWsfbAsR6JIFtFcaDvsVa5NseIJkw3V7uiJYxpgfgweeJXqkgcT1C5tJynKFC3POleOdnA2TeI8n9zEwWMtvTtrOYc2ixBerTtu/bvetZA2AYcFgweJciuJfmmwwDo60FjqsREzb2br8Gd34fJs7a1BpZyCYY5Zg9610nY0ubellcX4ZVOF0QtoH20DlyQtT+NUCerDbVN4pwKK0lE7VFOUwh5YdfYPL6ahK3IqQvLzKawztXDAKIBtVoEJk2YsqnZepv9vHSHIvnRkbzfbPv52muJ60R9Kf69DGah3dpHt61CPGLS5m8uJXM8Ocg3mUHLVwVocltOeOhoDM8H4ZsBQyFtNTOWkH51wB5MihmfxMCRGsjTDxQc5XOBKS/xtjtSkavRshcXYB3cSWcL7STZBpEqf4LS/AvrMC/mIN/acH7RIvs719cgj8n0r0vep/uXX22CG4sw72cg2f8uQVwcQlcXoh/KULsfITJC0VMX/t7ZLQvYKzT1uCSz+hlTI0CZTYrSjV7rtgu5HoLOKQuNOAijXdIsxniW/D+29zEUjzcIe27NpVewsZVbtJeRu+s5+H1COnr8+CSIlrSHsvh0jy4PM/Yw97lVfiXF5sB1aC+L3Rpsb2HS0ufukU5YJdz3p/7vrwQ70oO8cs5pK6thGv5cKUALmqCdjnOhRyiQ2vI3v8XpB9+hezEOUgZO9gWkvAn8bLKywusgEDGWQyEk8WB5ngrOEKQqP0Wv77NAaKYuGZYlbvl4GeVyKe850OM3N3G6M0QIDKllsIFMVMErszDubyK7JU8vCuL8a/Mf59oocl9EqMJqE/bKm/Kv6JrPAvN/dmz1+YzdT1CbHgp7s0KuFJhtfKFUvwrH8e9qYrpbZAew/fs/IWiUWaxljuFrw2LvgEgdgnFjGllEfNIY4RFML7FwAgv/20NEClnVTPMKn6ueirelF0qljnF6L0PMHYrggaRSznW11CI93IE/6qK2q8kbQAiJps7kzzrud5VK4kFjqemq88CDJ37bM+tvo3fWcz0neVMX80jeqGY5MX1cOP7YOSLEDsNWWUdWjNK/qIAYUBiFnBoCfAjDTLznQ1JfqPfEVhZOk6LpRT+tcgJ2fmb336bA8TD99K4qupoikQoy1MiqZ+Je59i4lYOzjXZxEpHj1jtEURU0tdXkL6+yiTmce053he6ugD/2iLcOZLO5apowbPRHJ9ffZu6XcbEjXxGrkcYv1lK+s6/gIk3ID5uI1WBby1RpjWAqqWmajZmnLQc4zGAyDmXnSxnUl58wP86XuCYmVlXzq6WI2vlvQb8W/f69gaIOtBRRpvWWA/bNdYSKpnrTN39DNO3i3CursLY6gLIFRuPd29ESN1YQuLmCsOc7ws4rj2Hb2gB7vUFFiRzaN8vcKjP3KsrSF5ea9Lqo3eex5n6p5B5E3zt92gDUI7WcHguGT9lSNEqJSEaVaLIVYAVtdb8CjPDNQEcHKcvtRRmJjdLK/VjM6b1tw4ez1zV5Ft5a+/h2gKIBI4q0JlU6LvBwDwgevcnid3egHe1CC4vseBQTP5GBO9WhMRwDonbS3FvLAQ58u8LzYfr8/FuiBbOoV0I156Rruse5vj8V3Nxr+yAG/8ERv4Akk1mrYakuoYl5vlmWWzKyZr14mZfu0BDSFPITJL8F+m91gLNFMkzi5ZmAWSWtlFJpYTZy16ZvZKI37rXt78Gyfi2IIJZTKNUaYFmgqm7v8T07VfIXiuxTBTM5gog7q0IyeH5hrybFjT6/BGJYcQ4Ak9Ilpm5MW/WcW85R98F5z1i+Hl4TzxH54fnBNc357/H999wXd3bbGafHwBoCVxdakkmp55p9rla+xHchwVreB2dn2OvoWMM5cD1HNRv2WtFMPxD8FD+Rp9d3aiSs6aMaYqEaoR4abP2/tEiJIFAzrnW1atVnlWoPULzSu1jDsfbahBpkb82sd5ROEj2hLULg8VVEiiph7jRL5Gd+H4SwyW4dyJwOwK3xAg5cHMZ7vB8nLsR0Hez6XYE//ZC/FvLcG8tnyH97d/KgdvPwXDE0h0da8m9GcG58RzpazmkruaQuLqI+JUFZG8vIDs8D2c4gnMngjdsSeeZ+7n5HNycPze6FcG/E8G9Z1u9N/cWXts8rwCRC0ZQlMD1fNBz6BkeO34+7u0cnGHRQtzh5+zz3iiAaysMOPxrEdwruTg38snciTA9vB7YbXaHxZ0GN2N3AJgpMiGtELzMG9lMoc7Qd/Z7e0w4saHv9X7Wef+nvXMNte266vg65+xzzj7Pe+7Nuff03pt3G1objG1ME7W9IpVQCTVSqpZUKkZMiSik2pp+CKgfzAcpVBFbNdoiFB/UQCBSIaCxRaGlEUKj1UaTe85+v9+P9V4/+c+51r773ua2+ZDmZF+yYbDW2WudNedce/zHGHOOMcfQDenqlT21pSNMVpP5e7P/eQ2Pi61BjLpo2fyFenN6twKI1yAYfgGv+wCj8gFBykAGJIe7cLhHUlw2zDVj9pTpzffFVcssxQ3C4gaRoXUiAUf/V7IMaRhMIBOVVgxDhUeb+IfbeEebuEdr+KVlw0xBeQ4gApWYV9pLx1ekZSjM0woUrqDisgG/gB6lNGN68/xlOBRAduHidRYcR1skxRU79jmA6DuBIyht4JUFEgsYLp6Bl09YgBw6hC/t4R+ewa+t06v+KPCNWVraLD3t/PE15NVjedSCA0RBbG0SJfkUQLIZn9cmGn+JsP8rDCoHeLWUoSVZ5wEiUBxtw+EpC5qjbZLChmEgaZ2M6SSZDSikPTIm1bmeV1mGSg7Ka1DKQ3ELSlvEpTxROWe0lJ5zuXRfsYx7tGo1wByDZ22a9tUHUUm0bLSeQJqRwBsW9ggLu/Z6phHNuASOdduOjuqrKAW3GY/uS7/XM/W8oLx+OUAO94y3XCBOjhyiQwmNMwT1c4waHzTlyuYBceX5sXD1a9jowgNEkaAJw0srI9IickxNvkwyfJhh5Rx+PZXyxSU4OgFHJ43Ej8s5OHwLXLzJHgsnoZg31y4zu8pLICqtXKJiDor6O2OyHJRWobgOZdEqSWWZuOIQV+fMOPWhoBCNbShsEpdXCGvWTAqrVx6XiCpLhFUdVwirK5cdo3KeqLBvSIBUW7N+q39qR6Q2pS10vWr7Y8ZeEqgtaOLSGmF5E7+Sx6+uEVbWDMiTw004WjX3xUUHX1TZJ27eRdB+xGQ3VMK7q9FryKvH8qhrACADU/4sVLmRTIOoypVqjkw/ybBy/rsBUjhBXF5CTBEfnic+vIm4cNL8PQNCYQcO9y1wdCxsg5hODJWZJjqXmXSZqSTQrBmQJBULkkQAEXOKStI8q1DYgKNdKJwkKl5HXLiOqHiSuHiCqLRDLO90OY8YWeBQfzXXENiiWnrUuUBS2jb3azy2jysWFCnzZyDIwGPGXs4ZcGZjEcAMQKpr+FVpPgFkjeRIgmDJ9F3j8CoOXv0MtD8Cg88DxauCQ6BZ9M+CA0TqYmQAIoetqvVaM0t5tP4VvN9nVLmZoGElp2XOXSjuoh87ruaIi6dJCgck5S0SmUoymaQBCqfg6ACOzkJhH4oblrkFDgMQSdVV4osOiZaOj7R8rIntBklph6SyTVzbJK6vkEiDZSSwGI0iIOVtO4XTcHTatqN2i3tQ3IGS2pQ2kgknU+6SFphpA2mfWo64sk5S3ki119y92f9Iu5W27DjLW8QpeM1zypqPbRFVdghqqwS1HFFV4F414zL3qJ26w7Tu4LbOQ+dRGP9zmsl/0WFw9f4vPEC0dq4sF0EYm4TEBiDBANxvgv8ZhtVb8RsOSU2MLem9C5LQ6Q8e1WQGrVqGETBKYsydOQYVYFKmFrPpXPMMAefoPMHhJkEhT1DcJSjvE1UPiOpvIWyeIWrv4TVX8VoOQdtS3HKImw5JMwWNeZ6kdEoFmWnSMK90FHA1n0iPpRxx3TECQMxrxqL5lsYqyjSXQCYAHp0nKZwnKe4bQOkdWNBdDSA5Qk329ZyWQ9R0GDUdJu3boPtn4B7aBGxX56+Fv7LgALGhCcqDpGTP0iIGICai97/A/3OGldssQIzUFhMKAFsWIA2HSFRPtUl5awYgM58QIPR/lzGbJvGnSApniUoHTKs7TGu7TGvXM629E7f2Ptz6B/DqP4vfuJ9h6f0My+9lXHkX49oPMandilu/Aa9+lrB+ykr8kky3V0tWc2VzHb+2wbSxjltfNeOUttSYYgkFM/fSsvSOAXRydKMBiLRmXNkgrl7SNJdpkPqy1SBVh1CTeD2n5eA3Hfoth3H73baisetjizIuPA6uOoCFB4h2nYmU7yJK4nQeotpuSjL2JOPq7YQtB2RmVVahvA2VzRlAdM1I9NoqSXUTypv2PgFDjNFO/7eYJzw8QVg4RVw5CXrZgg4AAAtoSURBVO1NktEq3bbDoJ/HG78L/Acg/AxET0P0gu1DUAXvJZh+E8ZfgcET0H2cpPVJks4DJK0fgc710DpH3NwnrO/h17bwqmu41WW8umx+B6/x3TSt5Um6dzOu30W3dJpBZQWv48DQgZEDfS3drpKUdqFyGqpnoLZPXN4lKGziyjko8NeXobpDUjtB1FgjauZIGjk7fr23ngNdh2HNodtycMf3wvg/bKzVnMviqly2wBcWHCByKcndZGM7zTZNpThX2Luv3K1fYVK7IwWImECTZwEkTyIp23TMtVAmT32JpLYC1ZRpxDiipv7OQ/mAuHQ9fuU00/oWk7ZDv+vQ7p+mN76bIHwQ+CPgqxBXLfMoM2ZGZiuEijMewvQ5m5zZ+xuYPgbex8F9CNwHYfIxkvFHiEcfJhrdz7DxfobNCwxb72XY+rHLqf4zMHiUuPfbBIMP4vVvZ9o9ybTtGLNO4Pc1udcSdG0DGinVNohKm4SFHMjUayxBfZu4sUvcXCdurUBTpPELaBlAlui0tnHHD8BEmeJTjb3AAPh+XV98gJgANoFEOkSe3DSpq+KzkmcZ1d5NIKmqH7y6DtUtqK0bE0TAkLQUGUbINI00R00T9h2oHED5RpLqzfiNc0xaJ+h3lul2HarNk/T6v8Zw9DmI/xH4lg2YNHn6bbIVw0RZaQOFsmq/ihIuKwI5Ua5ZBVkeXkEXbTkwlQTzXgTvf9KjzkWqN/J/4L4I4+fBfxaSv4LwEdz+Bbr1M3SqDoOqw7TmmFU8CQOjDVtL0MpBbQ2qcyCob84BRPdYs8ocew5xZ4lBbYtu++1Mp58CL417e1ODfD+MHd/1zDeo1V3l3FNu1kRhpAohVV3j+BvG/Ai7S9CUFM1DbRsa6ySadIrqW0SSrGIgMYWOAkhVK0L7UD5PVLkBt3aGcWufQfeAweAWBoMfptv7RfzpU/iT75AombRSYipUNTH1XAh8peyPbck1PyJRhgl5+udJ4eAaQLZMHdnVOFVDMqtyuq65laK/rzjOIgdUU8/klnoK3MeYdO6jU7uJTjXHpOnga5wyFWe0DNIS+jsDQiNP3Ngmaq0TtZcu3avrPYewk6PfOE2v89P43mchTOv4Lf5K7vdk4IXWIBlAxDeKH1X5MlOlT3HRRv0/z6R+D1FvGdrr1sSo70Azbxggbmsyu2fImFIZQBrSNntQvc7Y5V4jz6jt0Ovs0u/dyWT0q0STJ0imXzf17xJhMiviog2NgUK8lSAwxo083GiKH3oEQWTvU6oi5eFWOq8AVB5bKf7NMbT15ZXuX3Xm9RyVZ1ZMplFEc0cpJBNBYMKYhKgaRP8O7ufwex9l1Lwdt3OCsOsQSYvOAJKedx3Ivm+tkbS2iNt54s6y/V7XDUBWCDp5hs23Mug+SBT+A9A3+zNM+9+TxRb74jUEEC33XgmQbzNt/ARxfwU6eWhuQmPbAqTjkHQEkG2o71oTbAYQzTs2jV0uDeO39ph0rmc6uIA3fgS8v4egOB93Zwq8yKpTni5PlY5izYtk9qkYp6JOxzY1v8K2Vc5R6wjTtE55Visv3RCUKhS7IGeUi4LzsgC9YC7LoA0X97VXQgGwZhVPCRFeAO8JGD5E3LsLBmegl7NMn40xM7kEGoGklSNpbbwyQDrrBJ0NRq07mPQfI4m+ZnZwqp/XuALJsrsvJsqNBpltotEOs4HdU6BfTltEoheZNt9HPJREzENrywKktW5XZnoOSVvmRg5km18pYVs5osZJovZ7oKeUNV8A7zkIW2memjTwVB2RRSdGjxLCWKtq6o9KgGXFgurEtEzcWKLiLaaSZEzsTYi9MYk/MWSrsGpvvW/J7ItIH64G5klGZTRmjGtSH6kP1nyTSvoOeE9C52EY/DgMdu2YBRBjQq5BffWSpmivQnuDpLNB0l0xq1ZaudJ7STqb+J0dxq27mfY/C8l/ktAzuzmUSf1a/iy+BplJ3WzDjSoHmdJUEB/Rb96HPxRzbEB7DVoyr1ZIeg7RwCHpWk0ibWKo6xB3HWNSuK0bGFcvEDQ/AcOnIaxdmj+oqJFKHqkSkeFKa+jZdTUFUSqZRB8vruFTMRSmZecS7Z8XghPXFoFRIRjZW7Fr615okm9SqgagIhmKo8lIdpUSganZOGIYdEyZumy/t9EiMi81B4vK0Pw76PwOcfcCQec0QTN1LMr7LoAIBKIUIFq+pnNJgFjBsYHbyzPs3sN08NeQaGGhk9by07iv3c9CA0RAMOE+EmLSGjqa8lppYQma+NGniZO7jEc7C/kwXmzXIZSvYOLA2B4j18FzHSbuHsPBXXRbvwxodep/LcOKKWecqMYyu0bnGYlZdG73O1hO1n0Z6SGXwDQ7NzPwbD/qFUcB/pXIlAHQ8oTmX5bsttW0CfVV5L4Mk7/EG/wS7vBtuON1omkOvHW8wSphb90KjqY07J4xtYKuJubWl8JwnUnPYTB8D/CMWYyIgxrE3VQ4vAmQN+wbmAEkE+RGoqcOQwZMkj8k4l6C3qaVlNmk1F3DFUCCJZg6uAP5Ndbo925hNLmPIPhd4lCZxwvWrMmePzO89YVE9fFJUJk3mulYcNgkBjo3XbQYtQARSLxvEbt/QeB+FHf6TsajLYajJcbjNYLhBnRWQaZnW9p225il8UDaJQ+DTaaDJUbjnySOv27BqoDQWJrw+Mb/ejDlYmuQbJIoZsgY+DKAjHD5Y+B+kuGe9TDL6dVeIh6fYNhdI/KW8CcO49Eqo94dTFufhsHTELycMoCYQMtOWWNiCGkDgUNHXTiejwWIACESWNJIm6yrpm/qZ5r1JX4egi8RTn7DLFO3uuuM/FWCqQMCgzzm/TUQYCZ5GG9D6xR0zuIODphMfoFQBUfN+5apl6YsOZ7hvy6tLjRAZHWIKYz5MbNabLoY41tgyjT+PAk/TzLcTwGi5cwNgv4NdJtnGfZPMRnfSOz/FISPgvcv4CoaODVPDP8LfQKD3OFyjeuo744PHJY7sjiCOXCkczKZWppIJ5RT56Wck/JdfBvcv8V1H2Ls3s3QO4fnrs8BxCEZrRBNNmC8B63T0LqFYHAn/vS3CIKL1m+TCST9CNfw55oAiPmNMvEp71qWewmPSfBF4vhjBL2zYPwh20T1A/zunXRq9zDs30sw+TgEXwSesxNQ1S9XbXIpjxkOBAyFr6RfqtHjxkfaB5mZOrUaRWDRUvDYACSmSmKqwk7AV7HxLgT/DclTwOOMph/And5KMsgZEzToOfgDB3+cIx5uQ/skNG8j6X+I2PtT/KBpMi3JspL/xzT8JkDemG9ATJFVHJrZF2ZZNPVOyzoPv0wS/Tpe+3oSrWI194kb74DRzzHuChh/AsE/QfCSRYRQEcuZEZo0v+a5BggyVQQO1dhOwaHvdX5cH7UtzWnUqLqiRGpKhdMzWUOSNHtIGA8J/AmhOzXLyoQaR9XsJ/emjxO5H4bRLdBfwu87TAcOk5FDMNIqV564+TYYPAzBk3hB2zgtzWt+EyDH9cu/unYlMTVFNdktLFpsPIYWgQzTyAR5BpJH8btvNev5tG+G3gWIPwHTL0DUtNaTvG3hBCLtb1fohkgJ6dKJuJ4vEijm6dV19Qdzl/ohJpWWM1pEDskyCSUSswwbGLdJpKGFIUE0IIx7JhvlDPj+C2ZbANMPwehGgvEy3sRhqlU+1yHpO8Stm2D0KYifwY2qxtgMtYqctvuDGdwb46kLbmLNAyQtMGEcaRlA9JL/Dfg9wt7boasVmnfA+D7gD4BnLf9rSiFGk3POVDxSphTFVknKyqxKJ+kCXSaxj1t7aGjqg6ZGM0kuR+nLJLyUAiSe1d2QqIgZEtEhSnzj+Y+MM1UhKl8F/zfBvYPE3cL3HfzQIQwdkoEins/B+DHga0ySkpmeyRUj18yxatDXAUP/Dzulf7mPSc8LAAAAAElFTkSuQmCC

    annotation​

    A Kubernetes annotation for the NavLink custom resource.

    label​

    A Kubernetes label for the NavLink custom resource.

    sideLabel​

    Label that appears in the left navigation bar

    target​

    Sets the target property of the link's anchor tag (<a>), which (depending on browsers) determines if it opens in a new window or in an existing tab.

    The default value is _self, which opens the link on the current tab. To open the link in a new window or tab, set the target to _blank.

    For more information about the target property, see this page.

    toService​

    Has five fields that are constructed to create a URL like the following: https://<RANCHER_SERVER_URL>/k8s/clusters/<CLUSTER>/k8s/namespace/<NAMESPACE>/service/<SCHEME>:<NAME>:<PORT>/proxy/<PATH>

    For example, a link to a monitoring service can be set up as follows:

    • name: rancher-monitoring-grafana
    • namespace: cattle-monitoring-system
    • path: proxy/?orgId=1
    • port: "80"
    • scheme: http

    It is required to provide either the toService directive or the toURL directive.

    toUrl​

    Can be any link, even to links outside of the cluster.

    It is required to provide either the toService directive or the toURL directive.

    Link Examples

    This example NavLink YAML shows an example of configuring a NavLink to a Grafana dashboard:

    apiVersion: ui.cattle.io/v1
    kind: NavLink
    metadata:
      name: grafana
    spec:
      group: "Monitoring Dashboards"
      toURL: https://<RANCHER_SERVER_URL>/api/v1/namespaces/cattle-monitoring-system/services/http:rancher-monitoring-grafana:80/proxy/?orgId=1

    Adding the above YAML results in a link to Grafana being created, as shown in the following screenshot:

    Screenshot of Grafana Link

    This example YAML shows an example of toService used for the link target:

    apiVersion: ui.cattle.io/v1
    kind: NavLink
    metadata:
      annotations:
        key: annotation
        labels:
          key: label
      name: navlinkname
    spec:
      description: This is a description field # Optional.
      group: "group1" # Optional. If not provided, the links appear standalone.
      iconSrc: data:image/jpeg;base64,[icon source string is clipped for brevity]
      label: This is a label # Optional.
      sideLabel: A side label. # Optional.
      target: _blank #Optional. _blank opens the link in a new tab or window.
      toService: # toService or #toUrl needs to be provided.
        name: rancher-monitoring-grafana
        namespace: cattle-monitoring-system
        path: proxy/?orgId=1
        port: "80"
        scheme: http

    Adding the toService parameters above results in a link to Grafana being created, as shown in the following screenshot:

    Screenshot of Grafana Link

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html index 185b6e062d3..9744241d183 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html @@ -5,13 +5,13 @@ Configuring a Global Default Private Registry | Rancher Manager - +
    Version: v2.6

    Configuring a Global Default Private Registry

    You might want to use a private container registry to share your custom base images within your organization. With a private registry, you can keep a private, consistent, and centralized source of truth for the container images that are used in your clusters.

    There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

    This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed.

    For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the air-gapped installation guide.

    If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to pass in the registry credentials through the advanced cluster options every time you create a new cluster.

    Setting a Private Registry with No Credentials as the Default Registry​

    1. Log into Rancher and configure the default administrator password.
    2. Click ☰ > Global Settings.
    3. Go to the setting called system-default-registry and choose ⋮ > Edit Setting.
    4. Change the value to your registry (e.g. registry.yourdomain.com:port). Do not prefix the registry with http:// or https://.

    Result: Rancher will use your private registry to pull system images.

    Setting a Private Registry with Credentials when Deploying a Cluster​

    You can follow these steps to configure a private registry when you create a cluster:

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Choose a cluster type.
    4. In the Cluster Configuration go to the Registries tab and click Pull images for Rancher from a private registry.
    5. Enter the registry hostname and credentials.
    6. Click Create.

    Result: The new cluster will be able to pull images from the private registry.

    The private registry cannot be configured after the cluster is created.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-cluster-templates.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-cluster-templates.html index 10e984c8ce1..f4c51fa7e91 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-cluster-templates.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-cluster-templates.html @@ -5,13 +5,13 @@ Cluster Templates | Rancher Manager - +
    Version: v2.6

    Cluster Templates

    Cluster templates encompass both Kubernetes configuration and node pool configuration, allowing a single template to contain all the information Rancher needs to provision new nodes in a cloud provider and install Kubernetes on those nodes.

    Overview​

    Cluster templates are provided as Helm charts. To use them, you will need to clone and fork the templates, change them according to your use case, and then install the Helm charts on the Rancher management cluster. When the Helm chart is installed on the Rancher management cluster, a new cluster resource is created, which Rancher uses to provision the new cluster.

    After the cluster is provisioned using the template, no changes to the template will affect the cluster. After the cluster is created from the cluster template, its configuration and infrastructure can change, because no restrictions are enforced by cluster templates.

    Kubernetes Distribution​

    Cluster templates can use any Kubernetes distribution. For now, we provide an example with an RKE2 Kubernetes cluster. We may provide more examples in the future using other Kubernetes distributions.

    Versioning​

    Rancher doesn't manage version control for cluster templates. Version control is handled in the repository containing the template's Helm chart.

    RKE2 Cluster Template​

    The example repository for an RKE2 cluster template is here. As of Rancher v2.6.0, we provide an RKE2 cluster template and may add more in the future.

    Adding a Cluster Template to Rancher​

    In this section, you'll learn how to add the cluster template to the local cluster's chart repo list. The result is that Rancher will include the cluster template as an option when users install new Kubernetes clusters.

    Prerequisites:
    • You will need permission to install Helm charts on the local Kubernetes cluster that Rancher is installed on.
    • In order for the chart to appear in the form for creating new clusters, the chart must have the annotation catalog.cattle.io/type: cluster-template.
    1. Go to a cluster template example repository. Rancher's examples are in this GitHub repository. As of Rancher v2.6.0, we provide an RKE2 cluster template and add to more in the future.
    2. Fork the repository.
    3. Optional: Edit the cluster options by editing the values.yaml file. For help editing the file, see the cluster template's Helm chart README.
    4. Add the chart repository to Rancher. Click ☰ > Cluster Management.
    5. Go to the local cluster and click Explore.
    6. In the left navigation bar, click Apps & Marketplace > Chart Repositories.
    7. Click Create.
    8. Enter a name for the cluster template repository.
    9. Click Git Repository containing Helm chart definitions.
    10. In the Git Repo URL field, enter the URL for the repository. For example, https://github.com/rancher/cluster-template-examples.git.
    11. In the Git Branch field, enter the branch to use as the source for the template. Rancher's example repository uses main.
    12. Click Create.

    Result: The cluster template available from the Apps & Marketplace in Rancher's local cluster. It can now be used to deploy clusters.

    Restricted Admin access:

    If you are a restricted admin and don’t have access to the local cluster, you may still add new RKE2 templates and manage cluster repositories. To navigate to the chart repository, go to the left navigation bar and click ☰ > Cluster Management > Advanced > Repositories. You will bypass steps 1 - 6 above, then proceed to follow steps 7 - 12 to create the cluster template.

    Creating a Cluster from a Cluster Template​

    Prerequisites:
    • You will need permission to provision new Kubernetes clusters.
    • You will need cloud credentials for provisioning infrastructure using the template.
    • In order to show in the form for creating new clusters, the cluster template's Helm chart must have the catalog.cattle.io/type: cluster-template annotation.
    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click the name of your cluster template.
    4. Finish installing the Helm chart.

    Result: After Rancher provisions the new cluster, it is managed in the same way as any other Rancher-launched Kubernetes cluster. You can configure any options through the UI if the cluster template has options for the user to choose from.

    Updating a Cluster Created from a Cluster Template​

    You can update any clusters using a template from the Apps & Marketplace > Installed Apps page, given there is a new version of a template being used by those clusters.

    Deploying Clusters from a Template with Fleet​

    Prerequisites:
    • You will need permission to provision new Kubernetes clusters.
    • You will need cloud credentials for provisioning infrastructure using the template.
    • In order to show in the form for creating new clusters, the cluster template's Helm chart must have the catalog.cattle.io/type:cluster-template annotation.
    • In order to use a template as part of continuous delivery/GitOps, the cluster template needs to be deployed in the fleet-local namespace of the local cluster.
    • All values must be set in the values.yaml of the template.
    • Fleet repositories must follow the guidelines on this page. For RKE2 cluster templates, that means a fleet.yaml file must be added to the repository.
    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click Create Cluster from Template.

    Result: After Rancher provisions the new cluster, it is managed by Fleet.

    Uninstalling Cluster Templates​

    1. Click ☰ > Cluster Management.
    2. Go to the local cluster and click Apps & Marketplace > Chart Repositories.
    3. Go to the chart repository for your cluster template and click ⋮ > Delete.
    4. Confirm the deletion.

    Result: The cluster template is uninstalled. This action does not affect clusters created with the cluster template.

    An admin with access to the local cluster can also remove a cluster deployed via cluster templates through the Apps & Marketplace > Installed Apps page.

    Configuration Options​

    Cluster templates are flexible enough that they can be used to configure all of the following options:

    • Node configuration
    • Node pools
    • Pre-specified cloud credentials
    • Enable/configure an authorized cluster endpoint to get kubectl access to the cluster without using Rancher as a proxy
    • Install Rancher V2 monitoring
    • Kubernetes version
    • Assign cluster members
    • Infrastructure configuration such as AWS VPC/subnets or vSphere data center
    • Cloud provider options
    • Pod security options
    • Network providers
    • Ingress controllers
    • Network security configuration
    • Network plugins
    • Private registry URL and credentials
    • Add-ons
    • Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services

    For details on how to configure the template, refer to the cluster template's Helm chart README.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html index a13da346708..c5afbe74bd6 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html @@ -5,13 +5,13 @@ Cluster and Project Roles | Rancher Manager - +
    Version: v2.6

    Cluster and Project Roles

    Cluster and project roles define user authorization inside a cluster or project.

    To manage these roles,

    1. Click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles and go to the Cluster or Project/Namespaces tab.

    Membership and Role Assignment​

    The projects and clusters accessible to non-administrative users is determined by membership. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.

    When you create a cluster or project, Rancher automatically assigns you as the Owner for it. Users assigned the Owner role can assign other users roles in the cluster or project.

    note

    Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.

    Cluster Roles​

    Cluster roles are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: Owner and Member.

    • Cluster Owner:

      These users have full control over the cluster and all resources in it.

    • Cluster Member:

      These users can view most cluster level resources and create new projects.

    Custom Cluster Roles​

    Rancher lets you assign custom cluster roles to a standard user instead of the typical Owner or Member roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.

    Cluster Role Reference​

    The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, Cluster Owner and Cluster Member.

    Built-in Cluster RoleOwnerMember
    Create Projects✓✓
    Manage Cluster Backups            ✓
    Manage Cluster Catalogs✓
    Manage Cluster Members✓
    Manage Nodes (see table below)✓
    Manage Storage✓
    View All Projects✓
    View Cluster Catalogs✓✓
    View Cluster Members✓✓
    View Nodes✓✓

    Manage Nodes Permissions​

    The following table lists the permissions available for the Manage Nodes role in RKE and RKE2.

    Manage Nodes PermissionsRKERKE2
    SSH Access✓✓
    Delete Nodes✓✓
    Scale Clusters Up and Down✓*

    *In RKE2, you must have permission to edit a cluster to be able to scale clusters up and down.


    For details on how each cluster role can access Kubernetes resources, you can look them up in the Rancher UI:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Click the Cluster tab.
    4. Click the name of an individual role. The table shows all of the operations and resources that are permitted by the role.
    note

    When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Giving a Custom Cluster Role to a Cluster Member​

    After an administrator sets up a custom cluster role, cluster owners and admins can then assign those roles to cluster members.

    To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.

    To assign the role to a new cluster member,

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to assign a role to a member and click Explore.
    3. Click RBAC > Cluster Members.
    4. Click Add.
    5. In the Cluster Permissions section, choose the custom cluster role that should be assigned to the member.
    6. Click Create.

    Result: The member has the assigned role.

    To assign any custom role to an existing cluster member,

    1. Click ☰ > Users & Authentication.
    2. Go to the member you want to give the role to. Click the ⋮ > Edit Config.
    3. If you have added custom roles, they will show in the Custom section. Choose the role you want to assign to the member.
    4. Click Save.

    Result: The member has the assigned role.

    Project Roles​

    Project roles are roles that can be used to grant users access to a project. There are three primary project roles: Owner, Member, and Read Only.

    • Project Owner:

      These users have full control over the project and all resources in it.

    • Project Member:

      These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.

    note

    By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Read Only:

      These users can view everything in the project but cannot create, update, or delete anything.

    danger

    Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the owner or member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    Custom Project Roles​

    Rancher lets you assign custom project roles to a standard user instead of the typical Owner, Member, or Read Only roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles.

    Project Role Reference​

    The following table lists each built-in custom project role available in Rancher and whether it is also granted by the Owner, Member, or Read Only role.

    Built-in Project RoleOwnerMemberRead Only
    Manage Project Members✓
    Create Namespaces✓✓
    Manage Config Maps✓✓
    Manage Ingress✓✓
    Manage Project Catalogs✓
    Manage Secrets✓✓
    Manage Service Accounts✓✓
    Manage Services✓✓
    Manage Volumes✓✓
    Manage Workloads✓✓
    View Secrets✓✓
    View Config Maps✓✓✓
    View Ingress✓✓✓
    View Project Members✓✓✓
    View Project Catalogs✓✓✓
    View Service Accounts✓✓✓
    View Services✓✓✓
    View Volumes✓✓✓
    View Workloads✓✓✓
    Notes:
    • Each project role listed above, including Owner, Member, and Read Only, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
    • The Manage Project Members role allows the project owner to manage any members of the project and grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually.

    Defining Custom Roles​

    As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.

    When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource will not override a broader grant defined in a role that the custom role is inheriting from.

    Default Cluster and Project Roles​

    By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either cluster owner or project owner. However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.

    There are two methods for changing default cluster/project roles:

    • Assign Custom Roles: Create a custom role for either your cluster or project, and then set the custom role as default.

    • Assign Individual Roles: Configure multiple cluster/project roles as default for assignment to the creating user.

      For example, instead of assigning a role that inherits other roles (such as cluster owner), you can choose a mix of individual roles (such as manage nodes and manage storage).

    note
    • Although you can lock a default role, the system still assigns the role to users who create a cluster/project.
    • Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.

    Configuring Default Roles for Cluster and Project Creators​

    You can change the cluster or project role(s) that are automatically assigned to the creating user.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Click the Cluster or Project/Namespaces tab.
    4. Find the custom or individual role that you want to use as default. Then edit the role by selecting ⋮ > Edit Config.
    5. In the Cluster Creator Default or Project Creator Default section, enable the role as the default.
    6. Click Save.

    Result: The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the Cluster/Project Creator Default column.

    If you want to remove a default role, edit the permission and select No from the default roles option.

    Cluster Membership Revocation Behavior​

    When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster and a project within the cluster, that standard user loses their cluster roles but retains their project roles. In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:

    If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html index 62b2c6fc825..cb10c72481b 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html @@ -5,13 +5,13 @@ Custom Roles | Rancher Manager - +
    Version: v2.6

    Custom Roles

    Within Rancher, roles determine what actions a user can make within a cluster or project.

    Note that roles are different from permissions, which determine what clusters and projects you can access.

    danger

    It is possible for a custom role to enable privilege escalation. For details, see this section.

    Prerequisites​

    To complete the tasks on this page, one of the following permissions are required:

    Creating A Custom Role​

    While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.

    The steps to add custom roles differ depending on the version of Rancher.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Select a tab to determine the scope of the role you're adding. The tabs are:
    • Global: The role is valid for allowing members to manage global scoped resources.
    • Cluster: The role is valid for assignment when adding/managing members to clusters.
    • Project/Namespaces: The role is valid for assignment when adding/managing members to projects or namespaces.

    1. Click Create Global Role, Create Cluster Role or Create Project/Namespaces Role, depending on the scope.

    2. Enter a Name for the role.

    3. Optional: Choose the Cluster/Project Creator Default option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.

      Out of the box, the Cluster Creator Default and the Project Creator Default roles are Cluster Owner and Project Owner respectively.

    4. Use the Grant Resources options to assign individual Kubernetes API endpoints to the role.

      When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

      You can also choose the individual cURL methods (Create, Delete, Get, etc.) available for use with each endpoint you assign.

    5. Use the Inherit from options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.

    6. Click Create.

    Creating a Custom Role that Inherits from Another Role​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.

    The custom role can then be assigned to a user or group so that the role takes effect the first time the user or users sign into Rancher.

    To create a custom role based on an existing role,

    1. In the upper left corner, click ☰ > Users & Authentication.

    2. In the left navigation bar, click Roles.

    3. Click the Cluster or Project/Namespaces tab. Click Create Cluster Role or Create Project/Namespaces Role depending on the scope. Note: Only cluster roles and project/namespace roles can inherit from another role.

    4. Enter a name for the role.

    5. In the Inherit From tab, select the role(s) that the custom role will inherit permissions from.

    6. In the Grant Resources tab, select the Kubernetes resource operations that will be enabled for users with the custom role.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

    7. Optional: Assign the role as default.

    8. Click Create.

    Deleting a Custom Role​

    When deleting a custom role, all global role bindings with this custom role are deleted.

    If a user is only assigned one custom role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.

    Custom roles can be deleted, but built-in roles cannot be deleted.

    To delete a custom role,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Go to the custom global role that should be deleted and click ⋮ (…) > Delete.
    4. Click Delete.

    Assigning a Custom Role to a Group​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.

    When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom role that was assigned to the group. They would continue to have their individual Standard User role.

    Prerequisites:

    You can only assign a global role to a group if:

    To assign a custom role to a group, follow these steps:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Groups.
    3. Go to the existing group that will be assigned the custom role and click ⋮ > Edit Config.
    4. If you have created roles, they will show in the Custom section. Choose any custom role that will be assigned to the group.
    5. Optional: In the Global Permissions or Built-in sections, select any additional permissions that the group should have.
    6. Click Save..

    Result: The custom role will take effect when the users in the group log into Rancher.

    Privilege Escalation​

    The Configure Catalogs custom permission is powerful and should be used with caution. When an admin assigns the Configure Catalogs permission to a standard user, it could result in privilege escalation in which the user could give themselves admin access to Rancher provisioned clusters. Anyone with this permission should be considered equivalent to an admin.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html index 12c0339f6d4..c2693e9126d 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html @@ -5,13 +5,13 @@ Global Permissions | Rancher Manager - +
    Version: v2.6

    Global Permissions

    Permissions are individual access rights that you can assign when selecting a custom permission for a user.

    Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are four default global permissions: Administrator, Restricted Admin,Standard User and User-base.

    • Administrator: These users have full control over the entire Rancher system and all clusters within it.

    • Restricted Admin: These users have full control over downstream clusters, but cannot alter the local Kubernetes cluster.

    • Standard User: These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.

    • User-Base: User-Base users have login-access only.

    You cannot update or delete the built-in Global Permissions.

    Restricted Admin​

    A new restricted-admin role was created in Rancher v2.5 in order to prevent privilege escalation from the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster.

    The restricted-admin can create other restricted-admin users with an equal level of access.

    A new setting was added to Rancher to set the initial bootstrapped administrator to have the restricted-admin role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.

    To bootstrap Rancher with the restricted-admin as the initial user, the Rancher server should be started with the following environment variable:

    CATTLE_RESTRICTED_DEFAULT_ADMIN=true

    List of restricted-admin Permissions​

    The following table lists the permissions and actions that a restricted-admin should have in comparison with the Administrator and Standard User roles:

    CategoryActionGlobal AdminStandard UserRestricted AdminNotes for Restricted Admin role
    Local Cluster functionsManage Local Cluster (List, Edit, Import Host)YesNoNo
    Create Projects/namespacesYesNoNo
    Add cluster/project membersYesNoNo
    Deploy MulticlusterApp in local clusterYesNoNo
    Global DNSYesNoNo
    Access to management cluster for CRDs and CRsYesNoYes
    Save as RKE TemplateYesNoNo
    Security
    Enable authConfigure AuthenticationYesNoYes
    RolesCreate/Assign GlobalRolesYesNo (Can list)YesAuth webhook allows creating globalrole for perms already present
    Create/Assign ClusterRolesYesNo (Can list)YesNot in local cluster
    Create/Assign ProjectRolesYesNo (Can list)YesNot in local cluster
    UsersAdd User/Edit/Delete/Deactivate UserYesNoYes
    GroupsAssign Global role to groupsYesNoYesAs allowed by the webhook
    Refresh GroupsYesNoYes
    PSP'sManage PSP templatesYesNo (Can list)YesSame privileges as Global Admin for PSPs
    Tools
    Manage RKE TemplatesYesNoYes
    Manage Global CatalogsYesNoYesCannot edit/delete built-in system catalog. Can manage Helm library
    Cluster DriversYesNoYes
    Node DriversYesNoYes
    GlobalDNS ProvidersYesYes (Self)Yes
    GlobalDNS EntriesYesYes (Self)Yes
    Settings
    Manage SettingsYesNo (Can list)No (Can list)
    Apps
    Launch Multicluster AppsYesYesYesNot in local cluster
    User
    Manage API KeysYes (Manage all)Yes (Manage self)Yes (Manage self)
    Manage Node TemplatesYesYes (Manage self)Yes (Manage self)Can only manage their own node templates and not those created by other users
    Manage Cloud CredentialsYesYes (Manage self)Yes (Manage self)Can only manage their own cloud credentials and not those created by other users
    Downstream ClusterCreate ClusterYesYesYes
    Edit ClusterYesYesYes
    Rotate CertificatesYesYes
    Snapshot NowYesYes
    Restore SnapshotYesYes
    Save as RKE TemplateYesNoYes
    Run CIS ScanYesYesYes
    Add MembersYesYesYes
    Create ProjectsYesYesYes
    Feature Charts since v2.5
    Install FleetYesYesShould not be able to run Fleet in local cluster
    Deploy EKS clusterYesYesYes
    Deploy GKE clusterYesYesYes
    Deploy AKS clusterYesYesYes

    Changing Global Administrators to Restricted Admins​

    If Rancher already has a global administrator, they should change all global administrators over to the new restricted-admin role.

    This can be done through Security > Users and moving any Administrator role over to Restricted Administrator.

    Signed-in users can change themselves over to the restricted-admin if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.

    Global Permission Assignment​

    Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.

    Global Permissions for New Local Users​

    When you create a new local user, you assign them a global permission as you complete the Add User form.

    To see the default permissions for new users,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. The Roles page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the Global tab, in the New User Default column, the permissions given to new users by default are indicated with a checkmark.

    You can change the default global permissions to meet your needs.

    Global Permissions for Users with External Authentication​

    When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the New User Default global permissions. By default, Rancher assigns the Standard User permission for new users.

    To see the default permissions for new users,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. The Roles page has tabs for roles grouped by scope. Each table lists the roles in that scope. In the New User Default column on each page, the permissions given to new users by default are indicated with a checkmark.

    You can change the default permissions to meet your needs.

    Permissions can be assigned to an individual user with these steps.

    You can assign a role to everyone in the group at the same time if the external authentication provider supports groups.

    Custom Global Permissions​

    Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.

    When a user from an external authentication source signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default user permission. The standard user permission allows users to login and create clusters.

    However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of Administrator or Standard User, you can assign them a more restrictive set of custom global permissions.

    The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role.

    Administrators can enforce custom global permissions in multiple ways:

    Custom Global Permissions Reference​

    The following table lists each custom global permission available and whether it is included in the default global permissions, Administrator, Standard User and User-Base.

    Custom Global PermissionAdministratorStandard UserUser-Base
    Create Clusters✓✓
    Create RKE Templates✓✓
    Manage Authentication✓
    Manage Catalogs✓
    Manage Cluster Drivers✓
    Manage Node Drivers✓
    Manage PodSecurityPolicy Templates✓
    Manage Roles✓
    Manage Settings✓
    Manage Users✓
    Use Catalog Templates✓✓
    User-Base (Basic log-in access)✓✓

    For details on which Kubernetes resources correspond to each global permission,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. If you click the name of an individual role, a table shows all of the operations and resources that are permitted by the role.
    Notes:
    • Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at /v3/globalRoles.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Configuring Default Global Permissions​

    If you want to restrict the default permissions for new users, you can remove the user permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.

    note

    Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.

    To change the default global permissions that are assigned to external users upon their first log in, follow these steps:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles. On the Roles page, make sure the Global tab is selected.
    3. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting ⋮ > Edit Config.
    4. If you want to add the permission as a default, Select Yes: Default role for new users and then click Save. If you want to remove a default permission, edit the permission and select No.

    Result: The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the New User Default column.

    Configuring Global Permissions for Individual Users​

    To configure permission for a user,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Users.
    3. Go to the user whose access level you want to change and click ⋮ > Edit Config.
    4. In the Global Permissions and Built-in sections, check the boxes for each permission you want the user to have. If you have created roles from the Roles page, they will appear in the Custom section and you can choose from them as well.
    5. Click Save.

    Result: The user's global permissions have been updated.

    Configuring Global Permissions for Groups​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.

    After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.

    For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator refreshes the group memberships.

    For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the New User Default global permissions. By default, the New User Default permissions are equivalent to the Standard User global role, but the default permissions can be configured.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as New User Default. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator refreshes group memberships, whichever comes first.

    Prerequisites:

    You can only assign a global role to a group if:

    To assign a custom global role to a group, follow these steps:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Groups.
    3. Go to the group you want to assign a custom global role to and click ⋮ > Edit Config.
    4. In the Global Permissions, Custom, and/or Built-in sections, select the permissions that the group should have.
    5. Click Create.

    Result: The custom global role will take effect when the users in the group log into Rancher.

    Refreshing Group Memberships​

    When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.

    To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.

    An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.

    To refresh group memberships,

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Users.
    3. Click Refresh Group Memberships.

    Result: Any changes to the group members' permissions will take effect.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html index 18fb74453f5..f9111cf426d 100644 --- a/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html +++ b/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html @@ -5,13 +5,13 @@ Locked Roles | Rancher Manager - +
    Version: v2.6

    Locked Roles

    You can set roles to a status of locked. Locking roles prevent them from being assigned to users in the future.

    Locked roles:

    • Cannot be assigned to users that don't already have it assigned.

    • Are not listed in the Member Roles drop-down when you are adding a user to a cluster or project.

    • Do not affect users assigned the role before you lock the role. These users retain access that the role provides.

      Example: let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.

      To enforce it, before you add new users to the cluster, you should lock the following roles: Cluster Owner, Cluster Member, and Create Projects. Then you could create a new custom role that includes the same permissions as a Cluster Member, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.

    Roles can be locked by the following users:

    • Any user assigned the Administrator global permission.
    • Any user assigned the Custom Users permission, along with the Manage Roles role.

    Locking/Unlocking Roles​

    If you want to prevent a role from being assigned to users, you can set it to a status of locked.

    You can lock roles in two contexts:

    Cluster roles and project/namespace roles can be locked, but global roles cannot.

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Roles.
    3. Go to the Cluster tab or the Project/Namespaces tab.
    4. From the role that you want to lock (or unlock), select ⋮ > Edit Config.
    5. From the Locked option, choose the Yes or No radio button. Then click Save.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html b/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html index 0ae59dd5fa6..c6f13e3337c 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html @@ -5,13 +5,13 @@ Configure Alerts for Periodic Scan on a Schedule | Rancher Manager - +
    Version: v2.6

    Configure Alerts for Periodic Scan on a Schedule

    It is possible to run a ClusterScan on a schedule.

    A scheduled scan can also specify if you should receive alerts when the scan completes.

    Alerts are supported only for a scan that runs on a schedule.

    The CIS Benchmark application supports two types of alerts:

    • Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
    • Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a Fail state.
    Prerequisite

    Before enabling alerts for rancher-cis-benchmark, make sure to install the rancher-monitoring application and configure the Receivers and Routes. For more information, see this section.

    While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan. An example route configuration is here.

    To configure alerts for a scan that runs on a schedule,

    1. Please enable alerts on the rancher-cis-benchmark application (#enabling-alerting-for-rancher-cis-benchmark)
    2. In the upper left corner, click ☰ > Cluster Management.
    3. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    4. Click CIS Benchmark > Scan.
    5. Click Create.
    6. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    7. Choose the option Run scan on a schedule.
    8. Enter a valid cron schedule expression in the field Schedule.
    9. Check the boxes next to the Alert types under Alerting.
    10. Optional: Choose a Retention Count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
    11. Click Create.

    Result: The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under rancher-monitoring application.

    A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html b/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html index af273aa7576..04f2524e5ff 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html @@ -5,13 +5,13 @@ Create a Custom Benchmark Version for Running a Cluster Scan | Rancher Manager - +
    Version: v2.6

    Create a Custom Benchmark Version for Running a Cluster Scan

    There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.

    It is now possible to create a custom Benchmark Version for running a cluster scan using the rancher-cis-benchmark application.

    For details, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html b/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html index bb4410858d7..162bfa24cfb 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html @@ -5,13 +5,13 @@ Enable Alerting for Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.6

    Enable Alerting for Rancher CIS Benchmark

    Alerts can be configured to be sent out for a scan that runs on a schedule.

    Prerequisite:

    Before enabling alerts for rancher-cis-benchmark, make sure to install the rancher-monitoring application and configure the Receivers and Routes. For more information, see this section.

    While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan. An example route configuration is here.

    While installing or upgrading the rancher-cis-benchmark Helm chart, set the following flag to true in the values.yaml:

    alerts:
      enabled: true
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html b/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html index 52b091e44c4..920f1bb9c69 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html @@ -5,13 +5,13 @@ Install Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.6

    Install Rancher CIS Benchmark

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to install CIS Benchmark and click Explore.
    3. In the left navigation bar, click Apps & Marketplace > Charts.
    4. Click CIS Benchmark
    5. Click Install.

    Result: The CIS scan application is deployed on the Kubernetes cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html b/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html index 942e6505e08..70f97dfd1d3 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html @@ -5,13 +5,13 @@ Run a Scan Periodically on a Schedule | Rancher Manager - +
    Version: v2.6

    Run a Scan Periodically on a Schedule

    To run a ClusterScan on a schedule,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    5. Choose the option Run scan on a schedule.
    6. Enter a valid cron schedule expression in the field Schedule.
    7. Choose a Retention count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
    8. Click Create.

    Result: The scan runs and reschedules to run according to the cron schedule provided. The Next Scan value indicates the next time this scan will run again.

    A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.

    You can also see the previous reports by choosing the report from the Reports dropdown on the scan detail page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html b/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html index 2b2c8253d3e..e3356538be2 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html @@ -5,13 +5,13 @@ Run a Scan | Rancher Manager - +
    Version: v2.6

    Run a Scan

    When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.

    note

    There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.

    To run a scan,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. Click Create.
    5. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    6. Click Create.

    Result: A report is generated with the scan results. To see the results, click the name of the scan that appears.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html b/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html index ef3b2bfa514..7a7ddf76b79 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html @@ -5,13 +5,13 @@ Skip Tests | Rancher Manager - +
    Version: v2.6

    Skip Tests

    CIS scans can be run using test profiles with user-defined skips.

    To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.

    3. Click CIS Benchmark > Profile.

    4. From here, you can create a profile in multiple ways. To make a new profile, click Create and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile and click ⋮ Clone. If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the skipTests directive. You will also give the profile a name:

      apiVersion: cis.cattle.io/v1
      kind: ClusterScanProfile
      metadata:
        annotations:
          meta.helm.sh/release-name: clusterscan-operator
          meta.helm.sh/release-namespace: cis-operator-system
        labels:
          app.kubernetes.io/managed-by: Helm
        name: "<example-profile>"
      spec:
        benchmarkVersion: cis-1.5
        skipTests:
          - "1.1.20"
          - "1.1.21"

    5. Click Create.

    Result: A new CIS scan profile is created.

    When you run a scan that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as Skip.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html b/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html index 88743f0484f..6ec803be8e3 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html @@ -5,13 +5,13 @@ Uninstall Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.6

    Uninstall Rancher CIS Benchmark

    1. From the Cluster Dashboard, go to the left navigation bar and click Apps & Marketplace > Installed Apps.
    2. Go to the cis-operator-system namespace and check the boxes next to rancher-cis-benchmark-crd and rancher-cis-benchmark.
    3. Click Delete and confirm Delete.

    Result: The rancher-cis-benchmark application is uninstalled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html b/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html index 1bbfb1af044..d474bcefbf6 100644 --- a/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html +++ b/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html @@ -5,13 +5,13 @@ View Reports | Rancher Manager - +
    Version: v2.6

    View Reports

    To view the generated CIS scan reports,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. The Scans page will show the generated reports. To see a detailed report, go to a scan report and click the name.

    One can download the report from the Scans list or from the scan detail page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html b/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html index f47dc1fd459..3ead5e3a346 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html @@ -5,13 +5,13 @@ 1. Enable Istio in the Cluster | Rancher Manager - +
    Version: v2.6

    1. Enable Istio in the Cluster

    Prerequisites:
    • Only a user with the cluster-admin Kubernetes default role assigned can configure and install Istio in a Kubernetes cluster.
    • If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see this section.
    • To install Istio on an RKE2 cluster, additional steps are required. For details, see this section.
    • To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see this section.
    1. Click ☰ > Cluster Management.
    2. Go to the where you want to enable Istio and click Explore.
    3. Click Apps & Marketplace.
    4. Click Charts.
    5. Click Istio.
    6. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install.
    7. Optional: Configure member access and resource limits for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
    8. Optional: Make additional configuration changes to values.yaml if needed.
    9. Optional: Add additional resources or configuration via the overlay file.
    10. Click Install.

    Result: Istio is installed at the cluster level.

    Additional Config Options

    For more information on configuring Istio, refer to the configuration reference.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html b/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html index c49ee3fa421..a4ac0c115c4 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html @@ -5,13 +5,13 @@ 2. Enable Istio in a Namespace | Rancher Manager - +
    Version: v2.6

    2. Enable Istio in a Namespace

    You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.

    This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.

    Prerequisite:

    To enable Istio in a namespace, the cluster must have Istio installed.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. Click Cluster > Projects/Namespaces.
    4. Go to the namespace where you want to enable Istio and click ⋮ > Enable Istio Auto Injection. Alternately, click the namespace, and then on the namespace detail page, click ⋮ > Enable Istio Auto Injection.

    Result: The namespace now has the label istio-injection=enabled. All new workloads deployed in this namespace will have the Istio sidecar injected by default.

    Verifying that Automatic Istio Sidecar Injection is Enabled​

    To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the Containers section, you should see the istio-proxy container.

    Excluding Workloads from Being Injected with the Istio Sidecar​

    If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:

    sidecar.istio.io/inject: “false”

    To add the annotation to a workload,

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. Click Workload.
    4. Go to the workload that should not have the sidecar and edit as yaml
    5. Add the following key, value sidecar.istio.io/inject: false as an annotation on the workload
    6. Click Save.

    Result: The Istio sidecar will not be injected into the workload.

    note

    If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.

    Next: Add Deployments with the Istio Sidecar ​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html b/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html index 2e8024c1e32..cda8fe8fd19 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html @@ -5,13 +5,13 @@ 6. Generate and View Traffic | Rancher Manager - +
    Version: v2.6

    6. Generate and View Traffic

    This section describes how to view the traffic that is being managed by Istio.

    The Kiali Traffic Graph

    The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you are able to view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.

    Prerequisites:

    To enable traffic to show up in the graph, ensure you have prometheus installed in the cluster. Rancher-istio installs Kiali configured by default to work with the rancher-monitoring chart. You can use rancher-monitoring or install your own monitoring solution. Optional: you can change configuration on how data scraping occurs by setting the Selectors & Scrape Configs options.

    To see the traffic graph,

    1. In the cluster where Istio is installed, click Istio in the left navigation bar.
    2. Click the Kiali link.
    3. Click on Graph in the side nav.
    4. Change the namespace in the Namespace dropdown to view the traffic for each namespace.

    If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to v1 and v3 of the reviews service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.

    For additional tools and visualizations, you can go to Grafana, and Prometheus dashboards from the Monitoring Overview page

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html b/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html index 631de9e12f3..9af78c89a30 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html @@ -5,13 +5,13 @@ 4. Set up the Istio Gateway | Rancher Manager - +
    Version: v2.6

    4. Set up the Istio Gateway

    The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.

    You can use the Nginx Ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.

    To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two Ingresses.

    You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.

    You can route traffic into the service mesh with a load balancer or use Istio's NodePort gateway. This section describes how to set up the NodePort gateway.

    For more information on the Istio gateway, refer to the Istio documentation.

    In an Istio-enabled cluster, you can have two Ingresses: the default Nginx Ingress, and the default Istio controller.

    Enable an Istio Gateway

    The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Istio > Gateways.
    4. Click Create from Yaml.
    5. Paste your Istio Gateway yaml, or Read from File.
    6. Click Create.

    Result: The gateway is deployed, and will now route traffic with applied rules.

    Example Istio Gateway

    We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Istio > Gateways.
    4. Click Create from Yaml.
    5. Copy and paste the Gateway yaml provided below.
    6. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: Gateway
    metadata:
      name: bookinfo-gateway
    spec:
      selector:
        istio: ingressgateway # use istio default controller
      servers:
      - port:
          number: 80
          name: http
          protocol: HTTP
        hosts:
        - "*"
    ---

    Then to deploy the VirtualService that provides the traffic routing for the Gateway:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Istio > VirtualServices.
    4. Copy and paste the VirtualService yaml provided below.
    5. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: bookinfo
    spec:
      hosts:
      - "*"
      gateways:
      - bookinfo-gateway
      http:
      - match:
        - uri:
            exact: /productpage
        - uri:
            prefix: /static
        - uri:
            exact: /login
        - uri:
            exact: /logout
        - uri:
            prefix: /api/v1/products
        route:
        - destination:
            host: productpage
            port:
              number: 9080

    Result: You have configured your gateway resource so that Istio can receive traffic from outside the cluster.

    Confirm that the resource exists by running:

    kubectl get gateway -A

    The result should be something like this:

    NAME               AGE
    bookinfo-gateway   64m

    Access the ProductPage Service from a Web Browser​

    To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:

    http://<IP of Istio controller>:<Port of istio controller>/productpage

    To get the ingress gateway URL and port,

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Workload.
    4. Scroll down to the istio-system namespace.
    5. Within istio-system, there is a workload named istio-ingressgateway. Under the name of this workload, you should see links, such as 80/tcp.
    6. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append /productpage to the URL.

    Result: You should see the BookInfo app in the web browser.

    For help inspecting the Istio controller URL and ports, try the commands the Istio documentation.

    Troubleshooting

    The official Istio documentation suggests kubectl commands to inspect the correct ingress host and ingress port for external requests.

    Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller​

    You can try the steps in this section to make sure the Kubernetes gateway is configured properly.

    In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is istio and the value is ingressgateway. To make sure the label is appropriate for the gateway, do the following:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Workload.
    4. Scroll down to the istio-system namespace.
    5. Within istio-system, there is a workload named istio-ingressgateway. Click the name of this workload and go to the Labels and Annotations section. You should see that it has the key istio and the value ingressgateway. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.

    Next: Set up Istio's Components for Traffic Management​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html b/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html index 4e78bf91951..f0c39219474 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html @@ -5,13 +5,13 @@ 5. Set up Istio's Components for Traffic Management | Rancher Manager - +
    Version: v2.6

    5. Set up Istio's Components for Traffic Management

    A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are virtual services and destination rules.

    • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
    • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.

    This section describes how to add an example virtual service that corresponds to the reviews microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the reviews service.

    In this example, we take the traffic to the reviews service and intercept it so that 50 percent of it goes to v1 of the service and 50 percent goes to v2.

    After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.

    To deploy the virtual service and destination rules for the reviews service,

    1. Click ☰ > Cluster Management.

    2. Go to the cluster where Istio is installed and click Explore.

    3. In the cluster where Istio is installed, click Istio > DestinationRules in the left navigation bar.

    4. Click Create.

    5. Copy and paste the DestinationRule yaml provided below.

    6. Click Create.

    7. Click Edit as YAML and use this configuration:

      apiVersion: networking.istio.io/v1alpha3
      kind: DestinationRule
      metadata:
        name: reviews
      spec:
        host: reviews
        subsets:
        - name: v1
          labels:
            version: v1
        - name: v2
          labels:
            version: v2
        - name: v3
          labels:
            version: v3

    8. Click Create.

    Then to deploy the VirtualService that provides the traffic routing that utilizes the DestinationRule:

    1. Click VirtualService in the side nav bar.
    2. Click Create from Yaml.
    3. Copy and paste the VirtualService yaml provided below.
    4. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: reviews
    spec:
      hosts:
      - reviews
      http:
      - route:
        - destination:
            host: reviews
            subset: v1
          weight: 50
        - destination:
            host: reviews
            subset: v3
          weight: 50
    ---

    Result: When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the reviews service is divided evenly between v1 and v3.

    Next: Generate and View Traffic​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html b/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html index f3c6d5f03a8..7af6eb62abb 100644 --- a/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html +++ b/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html @@ -5,13 +5,13 @@ 3. Add Deployments and Services with the Istio Sidecar | Rancher Manager - +
    Version: v2.6

    3. Add Deployments and Services with the Istio Sidecar

    Prerequisite:

    To enable Istio for a workload, the cluster and namespace must have the Istio app installed.

    Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.

    To inject the Istio sidecar on an existing workload in the namespace,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to see the visualizations and click Explore.
    3. Click Workload.
    4. Go to the workload where you want to inject the Istio sidecar and click ⋮ > Redeploy. When the workload is redeployed, it will have the Envoy sidecar automatically injected.

    Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see istio-proxy alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.

    Add Deployments and Services​

    There are a few ways to add new Deployments in your namespace:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. Click Workload.
    4. Click Create.
    5. Click Deployment.
    6. Fill out the form, or Edit as Yaml.
    7. Click Create.

    To add a Service to your namespace:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. Click Service Discovery > Services.
    4. Click Create.
    5. Select the type of service that you want.
    6. Fill out the form, or Edit as Yaml.
    7. Click Create

    You can also create deployments and services using the kubectl shell

    1. Run kubectl create -f <name of service/deployment file>.yaml if your file is stored locally in the cluster
    2. Or run cat<< EOF | kubectl apply -f -, paste the file contents into the terminal, then run EOF to complete the command.

    Example Deployments and Services​

    Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the top navigation bar, open the kubectl shell.
    4. Run cat<< EOF | kubectl apply -f -
    5. Copy the below resources into the the shell.
    6. Run EOF

    This will set up the following sample resources from Istio's example BookInfo app:

    Details service and deployment:

    • A details Service
    • A ServiceAccount for bookinfo-details
    • A details-v1 Deployment

    Ratings service and deployment:

    • A ratings Service
    • A ServiceAccount for bookinfo-ratings
    • A ratings-v1 Deployment

    Reviews service and deployments (three versions):

    • A reviews Service
    • A ServiceAccount for bookinfo-reviews
    • A reviews-v1 Deployment
    • A reviews-v2 Deployment
    • A reviews-v3 Deployment

    Productpage service and deployment:

    This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.

    • A productpage service
    • A ServiceAccount for bookinfo-productpage
    • A productpage-v1 Deployment

    Resource YAML​

    # Copyright 2017 Istio Authors
    #
    #   Licensed under the Apache License, Version 2.0 (the "License");
    #   you may not use this file except in compliance with the License.
    #   You may obtain a copy of the License at
    #
    #       http://www.apache.org/licenses/LICENSE-2.0
    #
    #   Unless required by applicable law or agreed to in writing, software
    #   distributed under the License is distributed on an "AS IS" BASIS,
    #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    #   See the License for the specific language governing permissions and
    #   limitations under the License.

    ##################################################################################################
    # Details service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: details
      labels:
        app: details
        service: details
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: details
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-details
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: details-v1
      labels:
        app: details
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: details
          version: v1
      template:
        metadata:
          labels:
            app: details
            version: v1
        spec:
          serviceAccountName: bookinfo-details
          containers:
          - name: details
            image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Ratings service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: ratings
      labels:
        app: ratings
        service: ratings
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: ratings
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-ratings
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ratings-v1
      labels:
        app: ratings
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: ratings
          version: v1
      template:
        metadata:
          labels:
            app: ratings
            version: v1
        spec:
          serviceAccountName: bookinfo-ratings
          containers:
          - name: ratings
            image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Reviews service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: reviews
      labels:
        app: reviews
        service: reviews
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: reviews
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-reviews
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v1
      labels:
        app: reviews
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v1
      template:
        metadata:
          labels:
            app: reviews
            version: v1
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v2
      labels:
        app: reviews
        version: v2
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v2
      template:
        metadata:
          labels:
            app: reviews
            version: v2
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v3
      labels:
        app: reviews
        version: v3
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v3
      template:
        metadata:
          labels:
            app: reviews
            version: v3
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Productpage services
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: productpage
      labels:
        app: productpage
        service: productpage
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: productpage
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-productpage
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: productpage-v1
      labels:
        app: productpage
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: productpage
          version: v1
      template:
        metadata:
          labels:
            app: productpage
            version: v1
        spec:
          serviceAccountName: bookinfo-productpage
          containers:
          - name: productpage
            image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---

    Next: Set up the Istio Gateway​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html index a7218193197..e0b55c833d9 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html @@ -5,13 +5,13 @@ Adding Users to Clusters | Rancher Manager - +
    Version: v2.6

    Adding Users to Clusters

    If you want to provide a user with access and permissions to all projects, nodes, and resources within a cluster, assign the user a cluster membership.

    tip

    Want to provide a user with access to a specific project within a cluster? See Adding Project Members instead.

    There are two contexts where you can add cluster members:

    • Adding Members to a New Cluster

      You can add members to a cluster as you create it (recommended if possible).

    • Adding Members to an Existing Cluster

      You can always add members to a cluster after a cluster is provisioned.

    Editing Cluster Membership​

    Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.

    1. Click ☰ > Cluster Management.

    2. Go to the cluster you want to add members to and click ⋮ > Edit Config.

    3. In the Member Roles tab, click Add Member.

    4. Search for the user or group that you want to add to the cluster.

      If external authentication is configured:

    5. Assign the user or group Cluster roles.

      What are Cluster Roles?

      tip

      For Custom Roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the cluster.

    • To revoke cluster membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html index 31ac95b5b28..6ae91542e26 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html @@ -5,13 +5,13 @@ How the Authorized Cluster Endpoint Works | Rancher Manager - +
    Version: v2.6

    How the Authorized Cluster Endpoint Works

    This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for how to set up kubectl to directly access a cluster.

    About the kubeconfig File​

    The kubeconfig file is a file used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients).

    This kubeconfig file and its contents are specific to the cluster you are viewing. It can be downloaded from the cluster view in Rancher. You will need a separate kubeconfig file for each cluster that you have access to in Rancher.

    After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes contexts to access your downstream cluster.

    If admins have kubeconfig token generation turned off, the kubeconfig file requires rancher cli to be present in your PATH.

    Two Authentication Methods for RKE Clusters​

    If the cluster is not an RKE cluster, the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster.

    For RKE clusters, the kubeconfig file allows you to be authenticated in two ways:

    • Through the Rancher server authentication proxy: Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access.
    • Directly with the downstream cluster's API server: RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the kube-api-auth microservice) that Rancher set up.

    This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.

    To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on this page.

    These methods of communicating with downstream Kubernetes clusters are also explained in the architecture page in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.

    About the kube-api-auth Authentication Webhook​

    The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint, which is only available for RKE clusters. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

    During cluster provisioning, the file /etc/kubernetes/kube-api-authn-webhook.yaml is deployed and kube-apiserver is configured with --authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml. This configures the kube-apiserver to query http://127.0.0.1:6440/v1/authenticate to determine authentication for bearer tokens.

    The scheduling rules for kube-api-auth are listed below:

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    kube-api-authbeta.kubernetes.io/os:NotIn:windows
    node-role.kubernetes.io/controlplane:In:"true"    		noneoperator:Exists
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html index 49593d3d5d7..8639aa9d27e 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html @@ -5,13 +5,13 @@ Access a Cluster with Kubectl and kubeconfig | Rancher Manager - +
    Version: v2.6

    Access a Cluster with Kubectl and kubeconfig

    This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.

    For more information on using kubectl, see Kubernetes Documentation: Overview of kubectl.

    Accessing Clusters with kubectl Shell in the Rancher UI​

    You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster you want to access with kubectl and click Explore.
    3. In the top navigation menu, click the Kubectl Shell button. Use the window that opens to interact with your Kubernetes cluster.

    Accessing Clusters with kubectl from Your Workstation​

    This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.

    This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.

    Prerequisites:

    These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official Kubernetes documentation.

    1. Log into Rancher. Click ☰ > Cluster Management.
    2. Go to the cluster that you want to access with kubectl and click Explore.
    3. In the top navigation bar, click Download KubeConfig button.
    4. Save the YAML file on your local computer. Move the file to ~/.kube/config. Note: The default location that kubectl uses for the kubeconfig file is ~/.kube/config, but you can use any directory and specify it using the --kubeconfig flag, as in this command:
      kubectl --kubeconfig /custom/path/kube.config get pods
    5. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.

    Note on Resources Created Using kubectl​

    Rancher will discover and show resources created by kubectl. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.

    Authenticating Directly with a Downstream Cluster​

    This section intended to help you set up an alternative method to access an RKE cluster.

    This method is only available for RKE clusters that have the authorized cluster endpoint enabled. When Rancher creates this RKE cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to this page.

    We recommend that as a best practice, you should set up this method to access your RKE cluster, so that just in case you can’t connect to Rancher, you can still access the cluster.

    Prerequisites:

    The following steps assume that you have created a Kubernetes cluster and followed the steps to connect to your cluster with kubectl from your workstation.

    To find the name of the context(s) in your downloaded kubeconfig file, run:

    kubectl config get-contexts --kubeconfig /custom/path/kube.config
    CURRENT   NAME                        CLUSTER                     AUTHINFO     NAMESPACE
    *         my-cluster                  my-cluster                  user-46tmn
              my-cluster-controlplane-1   my-cluster-controlplane-1   user-46tmn

    In this example, when you use kubectl with the first context, my-cluster, you will be authenticated through the Rancher server.

    With the second context, my-cluster-controlplane-1, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE cluster directly.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below.

    When kubectl works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy.

    Connecting Directly to Clusters with FQDN Defined​

    If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named <CLUSTER_NAME>-fqdn. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-fqdn get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-fqdn get pods

    Connecting Directly to Clusters without FQDN Defined​

    If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named <CLUSTER_NAME>-<NODE_NAME>. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-<NODE_NAME> get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAME> get pods
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html b/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html index f7464d1f250..645826170a9 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html @@ -5,13 +5,13 @@ Adding a Pod Security Policy | Rancher Manager - +
    Version: v2.6

    Adding a Pod Security Policy

    Prerequisite:

    The options below are available only for clusters that are launched using RKE.

    When your cluster is running pods with security-sensitive configurations, assign it a pod security policy, which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running.

    You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster.

    1. Click ☰ > Cluster Management.

    2. Go to the cluster to which you want to apply a pod security policy and click ⋮ > Edit Config.

    3. From Pod Security Policy Support, select Enabled.

      note

      This option is only available for clusters provisioned by RKE.

    4. From the Default Pod Security Policy drop-down, select the policy you want to apply to the cluster.

      Rancher ships with policies of restricted and unrestricted, although you can create custom policies as well.

    5. Click Save.

    Result: The pod security policy is applied to the cluster and any projects within the cluster.

    note

    Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run.

    To check if a running workload passes your pod security policy, clone or upgrade it.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html b/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html index f25acacb359..62e591a662a 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html @@ -5,13 +5,13 @@ Assigning Pod Security Policies | Rancher Manager - +
    Version: v2.6

    Assigning Pod Security Policies

    Pod Security Policies are objects that control security-sensitive aspects of pod specification (like root privileges).

    Adding a Default Pod Security Policy​

    When you create a new cluster with RKE, you can configure it to apply a PSP immediately. As you create the cluster, use the Cluster Options to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster.

    Prerequisite:

    Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see Creating Pod Security Policies.

    note

    For security purposes, we recommend assigning a PSP as you create your clusters.

    To enable a default Pod Security Policy, set the Pod Security Policy Support option to Enabled, and then make a selection from the Default Pod Security Policy drop-down.

    When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html b/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html index f3951e239f0..3db500816eb 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html @@ -5,13 +5,13 @@ Removing Kubernetes Components from Nodes | Rancher Manager - +
    Version: v2.6

    Removing Kubernetes Components from Nodes

    This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes.

    When you use Rancher to install Kubernetes on new nodes in an infrastructure provider, resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.

    When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in Active state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again.

    What Gets Removed?​

    When cleaning nodes provisioned using Rancher, the following components are deleted based on the type of cluster node you're removing.

    Removed ComponentNodes Hosted by Infrastructure ProviderCustom NodesHosted ClusterRegistered Nodes
    The Rancher deployment namespace (cattle-system by default)✓✓✓✓
    serviceAccount, clusterRoles, and clusterRoleBindings labeled by Rancher✓✓✓✓
    Labels, Annotations, and Finalizers✓✓✓✓
    Rancher Deployment✓✓✓
    Machines, clusters, projects, and user custom resource definitions (CRDs)✓✓✓
    All resources create under the management.cattle.io API Group✓✓✓
    All CRDs created by Rancher v2.x✓✓✓

    Removing a Node from a Cluster by Rancher UI​

    When the node is in Active state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    Removing Rancher Components from a Cluster Manually​

    When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components.

    danger

    The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost.

    Removing Rancher Components from Registered Clusters​

    For registered clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions.

    After the registered cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher.

    danger

    This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost.

    After you initiate the removal of a registered cluster using the Rancher UI (or API), the following events occur.

    1. Rancher creates a serviceAccount that it uses to remove the Rancher components from the cluster. This account is assigned the clusterRole and clusterRoleBinding permissions, which are required to remove the Rancher components.

    2. Using the serviceAccount, Rancher schedules and runs a job that cleans the Rancher components off of the cluster. This job also references the serviceAccount and its roles as dependencies, so the job deletes them before its completion.

    3. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes.

    Result: All components listed for registered clusters in What Gets Removed? are deleted.

    Cleaning up Nodes​

    Windows Nodes​

    To clean up a Windows node, you can run a cleanup script located in c:\etc\rancher. The script deletes Kubernetes generated resources and the execution binary. It also drops the firewall rules and network settings.

    To run the script, you can use this command in the PowerShell:

    pushd c:\etc\rancher
    .\cleanup.ps1
    popd

    Result: The node is reset and can be re-added to a Kubernetes cluster.

    Docker Containers, Images, and Volumes​

    Based on what role you assigned to the node, there are Kubernetes components in containers, containers belonging to overlay networking, DNS, ingress controller and Rancher agent. (and pods you created that have been scheduled to this node)

    To clean all Docker containers, images and volumes:

    docker rm -f $(docker ps -qa)
    docker rmi -f $(docker images -q)
    docker volume rm $(docker volume ls -q)

    Mounts​

    Kubernetes components and secrets leave behind mounts on the system that need to be unmounted.

    Mounts
    /var/lib/kubelet/pods/XXX (miscellaneous mounts)
    /var/lib/kubelet
    /var/lib/rancher

    To unmount all mounts:

    for mount in $(mount | grep tmpfs | grep '/var/lib/kubelet' | awk '{ print $3 }') /var/lib/kubelet /var/lib/rancher; do umount $mount; done

    Directories and Files​

    The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using rm -rf /directory_name.

    note

    Depending on the role you assigned to the node, some of the directories will or won't be present on the node.

    Directories
    /etc/ceph
    /etc/cni
    /etc/kubernetes
    /etc/rancher
    /opt/cni
    /opt/rke
    /run/secrets/kubernetes.io
    /run/calico
    /run/flannel
    /var/lib/calico
    /var/lib/etcd
    /var/lib/cni
    /var/lib/kubelet
    /var/lib/rancher
    /var/log/containers
    /var/log/kube-audit
    /var/log/pods
    /var/run/calico

    To clean the directories:

    rm -rf /etc/ceph \
           /etc/cni \
           /etc/kubernetes \
           /etc/rancher \
           /opt/cni \
           /opt/rke \
           /run/secrets/kubernetes.io \
           /run/calico \
           /run/flannel \
           /var/lib/calico \
           /var/lib/etcd \
           /var/lib/cni \
           /var/lib/kubelet \
           /var/lib/rancher\
           /var/log/containers \
           /var/log/kube-audit \
           /var/log/pods \
           /var/run/calico

    Network Interfaces and Iptables​

    The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. To remove these components, a restart is recommended.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    If you want to know more on (virtual) network interfaces or iptables rules, please see the specific subjects below.

    Network Interfaces​

    note

    Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node.

    Interfaces
    flannel.1
    cni0
    tunl0
    caliXXXXXXXXXXX (random interface names)
    vethXXXXXXXX (random interface names)

    To list all interfaces:

    # Using ip
    ip address show

    # Using ifconfig
    ifconfig -a

    To remove an interface:

    ip link delete interface_name

    Iptables​

    note

    Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node.

    Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state.

    Chains
    cali-failsafe-in
    cali-failsafe-out
    cali-fip-dnat
    cali-fip-snat
    cali-from-hep-forward
    cali-from-host-endpoint
    cali-from-wl-dispatch
    cali-fw-caliXXXXXXXXXXX (random chain names)
    cali-nat-outgoing
    cali-pri-kns.NAMESPACE (chain per namespace)
    cali-pro-kns.NAMESPACE (chain per namespace)
    cali-to-hep-forward
    cali-to-host-endpoint
    cali-to-wl-dispatch
    cali-tw-caliXXXXXXXXXXX (random chain names)
    cali-wl-to-host
    KUBE-EXTERNAL-SERVICES
    KUBE-FIREWALL
    KUBE-MARK-DROP
    KUBE-MARK-MASQ
    KUBE-NODEPORTS
    KUBE-SEP-XXXXXXXXXXXXXXXX (random chain names)
    KUBE-SERVICES
    KUBE-SVC-XXXXXXXXXXXXXXXX (random chain names)

    To list all iptables rules:

    iptables -L -t nat
    iptables -L -t mangle
    iptables -L
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html b/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html index 6979188f77d..e91f296ba2a 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html @@ -5,13 +5,13 @@ Cloning Clusters | Rancher Manager - +
    Version: v2.6

    Cloning Clusters

    If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster.

    Duplication of registered clusters is not supported.

    Cluster TypeCloneable?
    Nodes Hosted by Infrastructure Provider✓
    Hosted Kubernetes Providers✓
    Custom Cluster✓
    Registered Cluster
    caution

    During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, not wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure.

    Prerequisites​

    Download and install Rancher CLI. Remember to create an API bearer token if necessary.

    1. Export Cluster Config​

    Begin by using Rancher CLI to export the configuration for the cluster that you want to clone.

    1. Open Terminal and change your directory to the location of the Rancher CLI binary, rancher.

    2. Enter the following command to list the clusters managed by Rancher.

        ./rancher cluster ls

    1. Find the cluster that you want to clone, and copy either its resource ID or NAME to your clipboard. From this point on, we'll refer to the resource ID or NAME as <RESOURCE_ID>, which is used as a placeholder in the next step.

    2. Enter the following command to export the configuration for your cluster.

        ./rancher clusters export <RESOURCE_ID>


    **Step Result:** The YAML for a cloned cluster prints to Terminal.
    1. Copy the YAML to your clipboard and paste it in a new file. Save the file as cluster-template.yml (or any other name, as long as it has a .yml extension).

    2. Modify Cluster Config​

    Use your favorite text editor to modify the cluster configuration in cluster-template.yml for your cloned cluster.

    note

    Cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    1. Open cluster-template.yml (or whatever you named your config) in your favorite text editor.

      caution

      Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.

    1. As depicted in the example below, at the <CLUSTER_NAME> placeholder, replace your original cluster's name with a unique name (<CLUSTER_NAME>). If your cloned cluster has a duplicate name, the cluster will not provision successfully.

      Version: v3
      clusters:
          <CLUSTER_NAME>: # ENTER UNIQUE NAME
          dockerRootDir: /var/lib/docker
          enableNetworkPolicy: false
          rancherKubernetesEngineConfig:
          addonJobTimeout: 30
          authentication:
              strategy: x509
          authorization: {}
          bastionHost: {}
          cloudProvider: {}
          ignoreDockerVersion: true

    2. For each nodePools section, replace the original nodepool name with a unique name at the <NODEPOOL_NAME> placeholder. If your cloned cluster has a duplicate nodepool name, the cluster will not provision successfully.

      nodePools:
          <NODEPOOL_NAME>:
          clusterId: do
          controlPlane: true
          etcd: true
          hostnamePrefix: mark-do
          nodeTemplateId: do
          quantity: 1
          worker: true

    3. When you're done, save and close the configuration.

    3. Launch Cloned Cluster​

    Move cluster-template.yml into the same directory as the Rancher CLI binary. Then run this command:

    ./rancher up --file cluster-template.yml

    Result: Your cloned cluster begins provisioning. Enter ./rancher cluster ls to confirm.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html index 34b22f63b9c..9bba0523e97 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html @@ -5,13 +5,13 @@ GlusterFS Volumes | Rancher Manager - +
    Version: v2.6

    GlusterFS Volumes

    note

    This section only applies to RKE clusters.

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. The logging of the kubelet will show: transport endpoint is not connected. To prevent this from happening, you can configure your cluster to mount the systemd-run binary in the kubelet container. There are two requirements before you can change the cluster configuration:

    • The node needs to have the systemd-run binary installed (this can be checked by using the command which systemd-run on each cluster node)
    • The systemd-run binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use)
    docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version
    caution

    Before updating your Kubernetes YAML to mount the systemd-run binary, make sure the systemd package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.

    services:
      kubelet:
        extra_binds:
          - "/usr/bin/systemd-run:/usr/bin/systemd-run"

    After the cluster has finished provisioning, you can check the kubelet container logging to see if the functionality is activated by looking for the following logline:

    Detected OS with systemd
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html index 581f61b9bcd..30f2ea871da 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html @@ -5,13 +5,13 @@ How Persistent Storage Works | Rancher Manager - +
    Version: v2.6

    How Persistent Storage Works

    A persistent volume (PV) is a piece of storage in the Kubernetes cluster, while a persistent volume claim (PVC) is a request for storage.

    There are two ways to use persistent storage in Kubernetes:

    • Use an existing persistent volume
    • Dynamically provision new persistent volumes

    To use an existing PV, your application will need to use a PVC that is bound to a PV, and the PV should include the minimum resources that the PVC requires.

    For dynamic storage provisioning, your application will need to use a PVC that is bound to a storage class. The storage class contains the authorization to provision new persistent volumes.

    Setting Up New and Existing Persistent Storage

    For more information, refer to the official Kubernetes documentation on storage

    About Persistent Volume Claims​

    Persistent volume claims (PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. A PVC is mounted into a workloads as a volume so that the workload can claim its specified share of the persistent storage.

    To access persistent storage, a pod must have a PVC mounted as a volume. This PVC lets your deployment application store its data in an external location, so that if a pod fails, it can be replaced with a new pod and continue accessing its data stored externally, as though an outage never occurred.

    Each Rancher project contains a list of PVCs that you've created, available from Resources > Workloads > Volumes. You can reuse these PVCs when creating deployments in the future.

    PVCs are Required for Both New and Existing Persistent Storage​

    A PVC is required for pods to use any persistent storage, regardless of whether the workload is intended to use storage that already exists, or the workload will need to dynamically provision new storage on demand.

    If you are setting up existing storage for a workload, the workload mounts a PVC, which refers to a PV, which corresponds to existing storage infrastructure.

    If a workload should request new storage, the workload mounts PVC, which refers to a storage class, which has the capability to create a new PV along with its underlying storage infrastructure.

    Rancher lets you create as many PVCs within a project as you'd like.

    You can mount PVCs to a deployment as you create it, or later, after the deployment is running.

    Setting up Existing Storage with a PVC and PV​

    Your pods can store data in volumes, but if the pod fails, that data is lost. To solve this issue, Kubernetes offers persistent volumes (PVs), which are Kubernetes resources that correspond to external storage disks or file systems that your pods can access. If a pod crashes, its replacement pod can access the data in persistent storage without any data loss.

    PVs can represent a physical disk or file system that you host on premise, or a vendor-hosted storage resource, such as Amazon EBS or Azure Disk.

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    Important:

    PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.

    Binding PVs to PVCs​

    When pods are set up to use persistent storage, they mount a persistent volume claim (PVC) that is mounted the same way as any other Kubernetes volume. When each PVC is created, the Kubernetes master considers it to be a request for storage and binds it to a PV that matches the minimum resource requirements of the PVC. Not every PVC is guaranteed to be bound to a PV. According to the Kubernetes documentation,

    Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.

    In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PV that has at least the amount of disk space required by the PVC.

    To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume.

    Provisioning New Storage with a PVC and Storage Class​

    Storage Classes allow you to create PVs dynamically without having to create persistent storage in an infrastructure provider first.

    For example, if a workload is bound to a PVC and the PVC refers to an Amazon EBS Storage Class, the storage class can dynamically create an EBS volume and a corresponding PV.

    The Kubernetes master will then bind the newly created PV to your workload's PVC, allowing your workload to use the persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html index 7aac0c7d856..7304276a498 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html @@ -5,13 +5,13 @@ Dynamically Provisioning New Storage in Rancher | Rancher Manager - +
    Version: v2.6

    Dynamically Provisioning New Storage in Rancher

    This section describes how to provision new persistent storage for workloads in Rancher.

    This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on how storage works.

    New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see this page.

    To provision new storage for your workloads, follow these steps:

    1. Add a storage class and configure it to use your storage.
    2. Use the Storage Class for Pods Deployed with a StatefulSet.

    Prerequisites​

    • To set up persistent storage, the Manage Volumes role is required.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.
    • The cloud provider must be enabled. For details on enabling cloud providers, refer to this page.
    • Make sure your storage provisioner is available to be enabled.

    The following storage provisioners are enabled by default:

    NamePlugin
    Amazon EBS Diskaws-ebs
    AzureFileazure-file
    AzureDiskazure-disk
    Google Persistent Diskgce-pd
    Longhornflex-volume-longhorn
    VMware vSphere Volumevsphere-volume
    Locallocal
    Network File Systemnfs
    hostPathhost-path

    To use a storage provisioner that is not on the above list, you will need to use a feature flag to enable unsupported storage drivers.

    1. Add a storage class and configure it to use your storage​

    These steps describe how to set up a storage class at the cluster level.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to dynamically provision persistent storage volumes and click Explore.
    3. Click Storage > Storage Classes.
    4. Click Create.
    5. Enter a name for your storage class.
    6. From the Provisioner drop-down, select the service that you want to use to dynamically provision storage volumes. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, use the Amazon EBS Disk provisioner.
    7. In the Parameters tab, fill out the information required for the service to dynamically provision storage volumes. Each provisioner requires different information to dynamically provision storage volumes. Consult the service's documentation for help on how to obtain this information.
    8. Click Create.

    Result: The storage class is available to be consumed by a PVC.

    For full information about the storage class parameters, refer to the official Kubernetes documentation..

    2. Use the Storage Class for Pods Deployed with a StatefulSet​

    StatefulSets manage the deployment and scaling of Pods while maintaining a sticky identity for each Pod. In this StatefulSet, we will configure a VolumeClaimTemplate. Each Pod managed by the StatefulSet will be deployed with a PersistentVolumeClaim based on this VolumeClaimTemplate. The PersistentVolumeClaim will refer to the StorageClass that we created. Therefore, when each Pod managed by the StatefulSet is deployed, it will be bound to dynamically provisioned storage using the StorageClass defined in its PersistentVolumeClaim.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to add use the StorageClass for a workload and click Explore.
    3. In the left navigation bar, click Workload.
    4. Click Create.
    5. Click StatefulSet.
    6. In the Volume Claim Templates tab, click Add Claim Template.
    7. Enter a name for the persistent volume.
    8. In the *StorageClass field, select the StorageClass that will dynamically provision storage for pods managed by this StatefulSet.
    9. In the Mount Point field, enter the path that the workload will use to access the volume.
    10. Click Launch.

    Result: When each Pod managed by the StatefulSet is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to Pod with a compatible PVC.

    To attach the PVC to an existing workload,

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to add use the StorageClass for a workload and click Explore.
    3. In the left navigation bar, click Workload.
    4. Go to the workload that will use storage provisioned with the StorageClass that you cared at click ⋮ > Edit Config.
    5. In the Volume Claim Templates section, click Add Claim Template.
    6. Enter a persistent volume name.
    7. In the *StorageClass field, select the StorageClass that will dynamically provision storage for pods managed by this StatefulSet.
    8. In the Mount Point field, enter the path that the workload will use to access the volume.
    9. Click Save.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. If not, Rancher will provision new persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html index f116ba515a8..f79d2bb3d54 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html @@ -5,13 +5,13 @@ iSCSI Volumes | Rancher Manager - +
    Version: v2.6

    iSCSI Volumes

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes.

    Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the iSCSI initiator tool, which is embedded in the kubelet's rancher/hyperkube Docker image. From each kubelet (i.e., the initiator), the tool discovers and launches sessions with an iSCSI volume (i.e., the target). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure.

    If you encounter this issue, you can work around it by installing the initiator tool on each node in your cluster. You can install the iSCSI initiator tool by logging into your cluster nodes and entering one of the following commands:

    PlatformPackage NameInstall Command
    Ubuntu/Debianopen-iscsisudo apt install open-iscsi
    RHELiscsi-initiator-utilsyum install iscsi-initiator-utils -y

    After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below.

    Notes

    • Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the open-iscsi (deb) or iscsi-initiator-utils (yum) package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.

    • The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes.

    services:
      kubelet:
        extra_binds:
          - "/etc/iscsi:/etc/iscsi"
          - "/sbin/iscsiadm:/sbin/iscsiadm"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html index ec3a62ddd3c..7b11bc01f22 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html @@ -5,13 +5,13 @@ Setting up Existing Storage | Rancher Manager - +
    Version: v2.6

    Setting up Existing Storage

    This section describes how to set up existing persistent storage for workloads in Rancher.

    note

    This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on how storage works.

    To set up storage, follow these steps:

    1. Set up persistent storage.
    2. Add a PersistentVolume that refers to the persistent storage.
    3. Use the PersistentVolume for Pods Deployed with a StatefulSet.

    Prerequisites​

    • To create a persistent volume as a Kubernetes resource, you must have the Manage Volumes role.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    1. Set up persistent storage​

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using vSphere, NFS, or Amazon's EBS.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see this page.

    2. Add a PersistentVolume that refers to the persistent storage​

    These steps describe how to set up a PersistentVolume at the cluster level in Kubernetes.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to add a persistent volume and click Explore.
    3. In the left navigation bar, click Storage > Persistent Volumes.
    4. Click Create.
    5. Enter a Name for the persistent volume.
    6. Select the Volume Plugin for the disk type or service that you're using. When adding storage to a cluster that's hosted by a cloud provider, use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the Amazon EBS Disk volume plugin.
    7. Enter the Capacity of your volume in gigabytes.
    8. Complete the Plugin Configuration form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation.
    9. Optional: In the Customize form, configure the access modes. This options sets how many nodes can access the volume, along with the node read/write permissions. The Kubernetes Documentation includes a table that lists which access modes are supported by the plugins available.
    10. Optional: In the Customize form, configure the mount options. Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin's vendor documentation for the mount options available.
    11. Click Create.

    Result: Your new persistent volume is created.

    3. Use the Storage Class for Pods Deployed with a StatefulSet​

    StatefulSets manage the deployment and scaling of Pods while maintaining a sticky identity for each Pod. In this StatefulSet, we will configure a VolumeClaimTemplate. Each Pod managed by the StatefulSet will be deployed with a PersistentVolumeClaim based on this VolumeClaimTemplate. The PersistentVolumeClaim will refer to the PersistentVolume that we created. Therefore, when each Pod managed by the StatefulSet is deployed, it will be bound a PersistentVolume as defined in its PersistentVolumeClaim.

    You can configure storage for the StatefulSet during or after workload creation.

    The following steps describe how to assign existing storage to a new StatefulSet:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure storage for the StatefulSet and click Explore.
    3. In the left navigation bar, click Workload > StatefulSets.
    4. Click Create.
    5. Choose the namespace where the workload will be deployed.
    6. Enter a name for the StatefulSet.
    7. On the Volume Claim Templates tab, click Add Claim Template.
    8. Click Use an existing Persistent Volume.
    9. In the Persistent Volumes field, select the Persistent Volume that you created.
    10. In the Mount Point field, enter the path that the workload will use to access the volume.
    11. Click Launch.

    Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    The following steps describe how to assign persistent storage to an existing workload:

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure storage for the StatefulSet and click Explore.
    3. In the left navigation bar, click Workload > StatefulSets.
    4. Go to the workload that you want to add the persistent storage to. Click ⋮ > Edit.
    5. On the Volume Claim Templates tab, click Add Claim Template.
    6. Click Use an existing Persistent Volume.
    7. In the Persistent Volumes field, select the Persistent Volume that you created.
    8. In the Mount Point field, enter the path that the workload will use to access the volume.
    9. Click Launch.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html index 1d95ccdca93..a3074a272a8 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html @@ -5,13 +5,13 @@ Using an External Ceph Driver | Rancher Manager - +
    Version: v2.6

    Using an External Ceph Driver

    These instructions are about using the external Ceph driver in an RKE2 cluster. If you are using RKE, additional steps are required. For details, refer to this section.

    Requirements​

    Make sure ceph-common and xfsprogs packages are installed on SLE worker nodes.

    Using the Ceph Driver with RKE​

    The resources below are fully compatible with RKE based clusters, but there is a need to do an additional kubelet configuration for RKE.

    On RKE clusters, the kubelet component is running in a Docker container and doesn't have access to the host's kernel modules as rbd and libceph by default.

    To solve this limitation, you can either run modprobe rbd on worker nodes, or configure the kubelet containers to automatically mount the /lib/modules directory from the host into the container.

    For the kubelet configuration, put the following lines into the cluster.yml file prior to RKE cluster provisioning. You can also modify the cluster.yml later in the Rancher UI by clicking on Edit Cluster > Edit as YAML and restarting the worker nodes.

    services:
      kubelet:
        extra_binds:
          - '/lib/modules:/lib/modules:ro'

    For more information about the extra_binds directive, refer to this section.

    Installing the ceph-csi driver on an RKE2 cluster​

    note

    These steps are needed for dynamic RBD provisioning only.

    For more information about the ceph-csi-rbd chart, refer to this page.

    To get details about your SES cluster, run:

    ceph mon dump

    Read its output:

    dumped monmap epoch 3
    epoch 3
    fsid 79179d9d-98d8-4976-ab2e-58635caa7235
    last_changed 2021-02-11T10:56:42.110184+0000
    created 2021-02-11T10:56:22.913321+0000
    min_mon_release 15 (octopus)
    0: [v2:10.85.8.118:3300/0,v1:10.85.8.118:6789/0] mon.a
    1: [v2:10.85.8.123:3300/0,v1:10.85.8.123:6789/0] mon.b
    2: [v2:10.85.8.124:3300/0,v1:10.85.8.124:6789/0] mon.c

    Later you'll need the fsid and mon addresses values.

    Install the ceph-csi Driver Using Helm​

    Run these commands:

    helm repo add ceph-csi https://ceph.github.io/csi-charts
    helm repo update
    helm search repo ceph-csi -l
    helm inspect values ceph-csi/ceph-csi-rbd > ceph-csi-rbd-values.yaml

    Modify the ceph-csi-rbd-values.yaml file and keep there only the required changes:

    # ceph-csi-rbd-values.yaml
    csiConfig:
      - clusterID: "79179d9d-98d8-4976-ab2e-58635caa7235"
        monitors:
          - "10.85.8.118:6789"
          - "10.85.8.123:6789"
          - "10.85.8.124:6789"
    provisioner:
      name: provisioner
      replicaCount: 2

    Make sure the ceph monitors are reachable from the RKE2 cluster, for example, by ping.

    kubectl create namespace ceph-csi-rbd
    helm install --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml
    kubectl rollout status deployment ceph-csi-rbd-provisioner -n ceph-csi-rbd
    helm status ceph-csi-rbd -n ceph-csi-rbd

    in case you'd like to modify the configuration directly via Helm, you may adapt the ceph-csi-rbd-values.yaml file and call:

    helm upgrade \
      --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml

    Creating RBD Ceph Resources​

    # Create a ceph pool:
    ceph osd pool create myPool 64 64

    # Create a block device pool:
    rbd pool init myPool

    # Create a block device image:
    rbd create -s 2G myPool/image

    # Create a block device user and record the key:
    ceph auth get-or-create-key client.myPoolUser mon "allow r" osd "allow class-read object_prefix rbd_children, allow rwx pool=myPool" | tr -d '\n' | base64
    QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ==

    # Encode the ceph user myPoolUser into a bash64 hash:
    echo "myPoolUser" | tr -d '\n' | base64
    bXlQb29sVXNlcg==

    # Create a block device admin user and record the key:
    ceph auth get-or-create-key client.myPoolAdmin mds 'allow *' mgr 'allow *' mon 'allow *' osd 'allow * pool=myPool' | tr -d '\n' | base64
    QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ==

    # Encode the ceph user myPoolAdmin into a bash64 hash:
    echo "myPoolAdmin" | tr -d '\n' | base64
    bXlQb29sQWRtaW4=

    Configure RBD Ceph Access Secrets​

    User Account​

    For static RBD provisioning (the image within the ceph pool must exist), run these commands:

    cat > ceph-user-secret.yaml << EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: ceph-user
      namespace: default
    type: kubernetes.io/rbd
    data:
      userID: bXlQb29sVXNlcg==
      userKey: QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ==
    EOF

    kubectl apply -f ceph-user-secret.yaml

    Admin Account​

    For dynamic RBD provisioning (used for automatic image creation within a given ceph pool), run these commands:

    cat > ceph-admin-secret.yaml << EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: ceph-admin
      namespace: default
    type: kubernetes.io/rbd
    data:
      userID: bXlQb29sQWRtaW4=
      userKey: QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ==
    EOF

    kubectl apply -f ceph-admin-secret.yaml

    Create RBD Testing Resources​

    Using RBD in Pods​

    # pod
    cat > ceph-rbd-pod-inline.yaml << EOF
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-inline
    spec:
      containers:
      - name: ceph-rbd-pod-inline
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        rbd:
          monitors:
          - 10.85.8.118:6789
          - 10.85.8.123:6789
          - 10.85.8.124:6789
          pool: myPool
          image: image
          user: myPoolUser
          secretRef:
            name: ceph-user
          fsType: ext4
          readOnly: false
    EOF

    kubectl apply -f ceph-rbd-pod-inline.yaml
    kubectl get pod
    kubectl exec pod/ceph-rbd-pod-inline -- df -k | grep rbd

    Using RBD in Persistent Volumes​

    # pod-pvc-pv
    cat > ceph-rbd-pod-pvc-pv-allinone.yaml << EOF
    apiVersion: v1
    kind: PersistentVolume
    metadata:
      name: ceph-rbd-pv
    spec:
      capacity:
        storage: 2Gi
      accessModes:
        - ReadWriteOnce
      rbd:
        monitors:
        - 10.85.8.118:6789
        - 10.85.8.123:6789
        - 10.85.8.124:6789
        pool: myPool
        image: image
        user: myPoolUser
        secretRef:
          name: ceph-user
        fsType: ext4
        readOnly: false
    ---
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: ceph-rbd-pvc
    spec:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 2Gi
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-pvc-pv
    spec:
      containers:
      - name: ceph-rbd-pod-pvc-pv
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        persistentVolumeClaim:
          claimName: ceph-rbd-pvc
    EOF

    kubectl apply -f ceph-rbd-pod-pvc-pv-allinone.yaml
    kubectl get pv,pvc,pod
    kubectl exec pod/ceph-rbd-pod-pvc-pv -- df -k | grep rbd

    Using RBD in Storage Classes​

    This example is for dynamic provisioning. The ceph-csi driver is needed.

    # pod-pvc-sc
    cat > ceph-rbd-pod-pvc-sc-allinone.yaml <<EOF
    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: ceph-rbd-sc
      annotations:
        storageclass.kubernetes.io/is-default-class: "true"
    provisioner: rbd.csi.ceph.com
    parameters:
       clusterID: 79179d9d-98d8-4976-ab2e-58635caa7235
       pool: myPool
       imageFeatures: layering
       csi.storage.k8s.io/provisioner-secret-name: ceph-admin
       csi.storage.k8s.io/provisioner-secret-namespace: default
       csi.storage.k8s.io/controller-expand-secret-name: ceph-admin
       csi.storage.k8s.io/controller-expand-secret-namespace: default
       csi.storage.k8s.io/node-stage-secret-name: ceph-admin
       csi.storage.k8s.io/node-stage-secret-namespace: default
    reclaimPolicy: Delete
    allowVolumeExpansion: true
    mountOptions:
       - discard
    ---
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: ceph-rbd-sc-pvc
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 2Gi
      storageClassName: ceph-rbd-sc
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-pvc-sc
    spec:
      containers:
      - name:  ceph-rbd-pod-pvc-sc
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        persistentVolumeClaim:
          claimName: ceph-rbd-sc-pvc
    EOF

    kubectl apply -f ceph-rbd-pod-pvc-sc-allinone.yaml
    kubectl get pv,pvc,sc,pod
    kubectl exec pod/ceph-rbd-pod-pvc-sc -- df -k | grep rbd

    RKE2 Server/Master Provisioning​

    sudo su
    curl -sfL https://get.rke2.io | sh -
    systemctl enable --now rke2-server

    cat > /root/.bashrc << EOF
    export PATH=$PATH:/var/lib/rancher/rke2/bin/
    export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
    EOF

    cat /var/lib/rancher/rke2/server/node-token
    token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED

    RKE2 Agent/Worker provisioning​

    mkdir -p /etc/rancher/rke2/

    cat > /etc/rancher/rke2/config.yaml << EOF
    server: https://10.100.103.23:9345
    token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED
    EOF

    curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -
    systemctl enable --now rke2-agent.service

    To import the cluster into Rancher, click ☰ > Cluster Management. Then on the Clusters page, click Import Existing. Then run the provided kubectl command on the server/master node.

    Tested Versions​

    OS for running RKE2 nodes: JeOS SLE15-SP2 with installed kernel-default-5.3.18-24.49

    kubectl version
    Client Version: version.Info{Major:"1", Minor:"18", GitVersion:"v1.18.4", GitCommit:"c96aede7b5205121079932896c4ad89bb93260af", GitTreeState:"clean", BuildDate:"2020-06-22T12:00:00Z", GoVersion:"go1.13.11", Compiler:"gc", Platform:"linux/amd64"}
    Server Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.7+rke2r1", GitCommit:"1dd5338295409edcfff11505e7bb246f0d325d15", GitTreeState:"clean", BuildDate:"2021-01-20T01:50:52Z", GoVersion:"go1.15.5b5", Compiler:"gc", Platform:"linux/amd64"}

    helm version
    version.BuildInfo{Version:"3.4.1", GitCommit:"c4e74854886b2efe3321e185578e6db9be0a6e29", GitTreeState:"clean", GoVersion:"go1.14.12"}

    Kubernetes version on RKE2 cluster: v1.19.7+rke2r1

    Troubleshooting​

    In case you are using SUSE's ceph-rook based on SES7, it might be useful to expose the monitors on hostNetwork by editing rook-1.4.5/ceph/cluster.yaml and setting spec.network.hostNetwork=true.

    Also for operating the ceph-rook cluster, it is useful to deploy a toolbox on the Kubernetes cluster where ceph-rook is provisioned by kubectl apply -f rook-1.4.5/ceph/toolbox.yaml Then all the ceph related commands can be executed in the toolbox pod, for example, by running kubectl exec -it -n rook-ceph rook-ceph-tools-686d8b8bfb-2nvqp -- bash

    Operating with the ceph - basic commands:

    ceph osd pool stats
    ceph osd pool delete myPool myPool --yes-i-really-really-mean-it
    rbd list -p myPool
    > csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38
    > image

    Delete the image: rbd rm csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 -p myPool

    CephFS commands in rook toolbox:

    ceph -s
    ceph fs ls
    ceph fs fail cephfs
    ceph fs rm cephfs --yes-i-really-mean-it
    ceph osd pool delete cephfs_data cephfs_data --yes-i-really-really-mean-it
    ceph osd pool delete cephfs_metadata cephfs_metadata --yes-i-really-really-mean-it

    To prepare a cephfs filesystem, you can run this command on a rook cluster:

    kubectl apply -f rook-1.4.5/ceph/filesystem.yaml
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html index 4b83307cbce..00e9d87dddb 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html @@ -5,13 +5,13 @@ NFS Storage | Rancher Manager - +
    Version: v2.6

    NFS Storage

    Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server.

    note

    • If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete adding storage.

    • This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.

    Recommended:

    To simplify the process of managing firewall rules, use NFSv4.

    1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage.

    2. Enter the following command:

      sudo apt-get install nfs-kernel-server

    3. Enter the command below, which sets the directory used for storage, along with user access rights. Modify the command if you'd like to keep storage at a different directory.

      mkdir -p /nfs && chown nobody:nogroup /nfs
      • The -p /nfs parameter creates a directory named nfs at root.
      • The chown nobody:nogroup /nfs parameter allows all access to the storage directory.

    4. Create an NFS exports table. This table sets the directory paths on your NFS server that are exposed to the nodes that will use the server for storage.

      1. Open /etc/exports using your text editor of choice.

      2. Add the path of the /nfs folder that you created in step 3, along with the IP addresses of your cluster nodes. Add an entry for each IP address in your cluster. Follow each address and its accompanying parameters with a single space that is a delimiter.

        /nfs <IP_ADDRESS1>(rw,sync,no_subtree_check) <IP_ADDRESS2>(rw,sync,no_subtree_check) <IP_ADDRESS3>(rw,sync,no_subtree_check)
        tip

        You can replace the IP addresses with a subnet. For example: 10.212.50.12&#47;24

      3. Update the NFS table by entering the following command:

        exportfs -ra

    5. Open the ports used by NFS.

      1. To find out what ports NFS is using, enter the following command:

        rpcinfo -p | grep nfs

      2. Open the ports that the previous command outputs. For example, the following command opens port 2049:

        sudo ufw allow 2049

    Result: Your NFS server is configured to be used for storage with your Rancher nodes.

    What's Next?​

    Within Rancher, add the NFS server as a storage volume and/or storage class. After adding the server, you can use it for storage for your deployments.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html index a14e06f4e22..253a5e7716d 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html @@ -5,13 +5,13 @@ Creating Persistent Storage in Amazon's EBS | Rancher Manager - +
    Version: v2.6

    Creating Persistent Storage in Amazon's EBS

    This section describes how to set up Amazon's Elastic Block Store in EC2.

    1. From the EC2 console, go to the ELASTIC BLOCK STORE section in the left panel and click Volumes.
    2. Click Create Volume.
    3. Optional: Configure the size of the volume or other options. The volume should be created in the same availability zone as the instance it will be attached to.
    4. Click Create Volume.
    5. Click Close.

    Result: Persistent storage has been created.

    For details on how to set up the newly created storage in Rancher, refer to the section on setting up existing storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html index 55dff10f2ff..52921495ce0 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html @@ -5,13 +5,13 @@ vSphere Storage | Rancher Manager - +
    Version: v2.6

    vSphere Storage

    To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a PersistentVolumeClaim.

    In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

    Prerequisites​

    In order to provision vSphere volumes in a cluster created with the Rancher Kubernetes Engine (RKE), the vSphere cloud provider must be explicitly enabled in the cluster options.

    Creating a StorageClass​

    tip

    The following steps can also be performed using the kubectl command line tool. See Kubernetes documentation on persistent volumes for details.

    1. Click ☰ > Cluster Management.

    2. Go to the cluster where you want to provide vSphere storage.

    3. In the left navigation bar, click Storage > StorageClasses.

    4. Click Create.

    5. Enter a Name for the StorageClass.

    6. Under Provisioner, select VMWare vSphere Volume.

    7. Optionally, specify additional properties for this storage class under Parameters. Refer to the vSphere storage documentation for details.

    8. Click Create.

    Creating a Workload with a vSphere Volume​

    1. In the left navigation bar, click Workload.
    2. Click Create.
    3. Click StatefulSet.
    4. In the Volume Claim Templates tab, click Add Claim Template.
    5. Enter a persistent volume name.
    6. In the Storage Class field, select the vSphere StorageClass that you created.
    7. Enter the required Capacity for the volume. Then click Define.
    8. Assign a path in the Mount Point field. This is the full path where the volume will be mounted in the container file system, e.g. /persistent.
    9. Click Create.

    Verifying Persistence of the Volume​

    1. In the left navigation bar, click Workload > Pods.

    2. Go to the workload you just created and click ⋮ > Execute Shell.

    3. Note the directory at root where the volume has been mounted to (in this case /persistent).

    4. Create a file in the volume by executing the command touch /<volumeMountPoint>/data.txt.

    5. Close the shell window.

    6. Click on the name of the workload to reveal detail information.

    7. Click ⋮ > Delete.

    8. Observe that the pod is deleted. Then a new pod is scheduled to replace it so that the workload maintains its configured scale of a single stateful pod.

    9. Once the replacement pod is running, click Execute Shell.

    10. Inspect the contents of the directory where the volume is mounted by entering ls -l /<volumeMountPoint>. Note that the file you created earlier is still present.

      workload-persistent-data

    Why to Use StatefulSets Instead of Deployments​

    You should always use StatefulSets for workloads consuming vSphere storage, as this resource type is designed to address a VMDK block storage caveat.

    Since vSphere volumes are backed by VMDK block storage, they only support an access mode of ReadWriteOnce. This setting restricts the volume so that it can only be mounted to a single pod at a time, unless all pods consuming that volume are co-located on the same node. This behavior makes a deployment resource unusable for scaling beyond a single replica if it consumes vSphere volumes.

    Even using a deployment resource with just a single replica may result in a deadlock situation while updating the deployment. If the updated pod is scheduled to a node different from where the existing pod lives, it will fail to start because the VMDK is still attached to the other node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html b/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html index b9f9d6502db..db13d4a564e 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html @@ -5,7 +5,7 @@ Cluster Autoscaler with AWS EC2 Auto Scaling Groups | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.6

    Cluster Autoscaler with AWS EC2 Auto Scaling Groups

    This guide will show you how to install and use Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

    We are going to install a Rancher RKE custom cluster with a fixed number of nodes with the etcd and controlplane roles, and a variable nodes with the worker role, managed by cluster-autoscaler.

    Prerequisites​

    These elements are required to follow this guide:

    • The Rancher server is up and running
    • You have an AWS EC2 user with proper permissions to create virtual machines, auto scaling groups, and IAM profiles and roles

    1. Create a Custom Cluster​

    On Rancher server, we should create a custom k8s cluster. Refer here to check for version compatibility.

    Be sure that cloud_provider name is set to amazonec2. Once cluster is created we need to get:

    • clusterID: c-xxxxx will be used on EC2 kubernetes.io/cluster/<clusterID> instance tag

    • clusterName: will be used on EC2 k8s.io/cluster-autoscaler/<clusterName> instance tag

    • nodeCommand: will be added on EC2 instance user_data to include new nodes on cluster

      sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CHECKSUM> <roles>

    2. Configure the Cloud Provider​

    On AWS EC2, we should create a few objects to configure our system. We've defined three distinct groups and IAM profiles to configure on AWS.

    1. Autoscaling group: Nodes that will be part of the EC2 Auto Scaling Group (ASG). The ASG will be used by cluster-autoscaler to scale up and down.

    • IAM profile: Required by k8s nodes where cluster-autoscaler will be running. It is recommended for Kubernetes master nodes. This profile is called K8sAutoscalerProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeAutoScalingInstances",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:SetDesiredCapacity",
                      "autoscaling:TerminateInstanceInAutoScalingGroup",
                      "autoscaling:DescribeTags",
                      "autoscaling:DescribeLaunchConfigurations",
                      "ec2:DescribeLaunchTemplateVersions"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
    1. Master group: Nodes that will be part of the Kubernetes etcd and/or control planes. This will be out of the ASG.

    • IAM profile: Required by the Kubernetes cloud_provider integration. Optionally, AWS_ACCESS_KEY and AWS_SECRET_KEY can be used instead using-aws-credentials. This profile is called K8sMasterProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:DescribeTags",
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ec2:DescribeRouteTables",
                      "ec2:DescribeSecurityGroups",
                      "ec2:DescribeSubnets",
                      "ec2:DescribeVolumes",
                      "ec2:CreateSecurityGroup",
                      "ec2:CreateTags",
                      "ec2:CreateVolume",
                      "ec2:ModifyInstanceAttribute",
                      "ec2:ModifyVolume",
                      "ec2:AttachVolume",
                      "ec2:AuthorizeSecurityGroupIngress",
                      "ec2:CreateRoute",
                      "ec2:DeleteRoute",
                      "ec2:DeleteSecurityGroup",
                      "ec2:DeleteVolume",
                      "ec2:DetachVolume",
                      "ec2:RevokeSecurityGroupIngress",
                      "ec2:DescribeVpcs",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:AttachLoadBalancerToSubnets",
                      "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancerPolicy",
                      "elasticloadbalancing:CreateLoadBalancerListeners",
                      "elasticloadbalancing:ConfigureHealthCheck",
                      "elasticloadbalancing:DeleteLoadBalancer",
                      "elasticloadbalancing:DeleteLoadBalancerListeners",
                      "elasticloadbalancing:DescribeLoadBalancers",
                      "elasticloadbalancing:DescribeLoadBalancerAttributes",
                      "elasticloadbalancing:DetachLoadBalancerFromSubnets",
                      "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
                      "elasticloadbalancing:ModifyLoadBalancerAttributes",
                      "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
                      "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:CreateListener",
                      "elasticloadbalancing:CreateTargetGroup",
                      "elasticloadbalancing:DeleteListener",
                      "elasticloadbalancing:DeleteTargetGroup",
                      "elasticloadbalancing:DescribeListeners",
                      "elasticloadbalancing:DescribeLoadBalancerPolicies",
                      "elasticloadbalancing:DescribeTargetGroups",
                      "elasticloadbalancing:DescribeTargetHealth",
                      "elasticloadbalancing:ModifyListener",
                      "elasticloadbalancing:ModifyTargetGroup",
                      "elasticloadbalancing:RegisterTargets",
                      "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
                      "iam:CreateServiceLinkedRole",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage",
                      "kms:DescribeKey"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }

      • IAM role: K8sMasterRole: [K8sMasterProfile,K8sAutoscalerProfile]

      • Security group: K8sMasterSg More info atRKE ports (custom nodes tab)

      • Tags: kubernetes.io/cluster/<clusterID>: owned

      • User data: K8sMasterUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add etcd+controlplane node to the k8s cluster

        #!/bin/bash -x

        cat <<EOF > /etc/sysctl.d/90-kubelet.conf
        vm.overcommit_memory = 1
        vm.panic_on_oom = 0
        kernel.panic = 10
        kernel.panic_on_oops = 1
        kernel.keys.root_maxkeys = 1000000
        kernel.keys.root_maxbytes = 25000000
        EOF
        sysctl -p /etc/sysctl.d/90-kubelet.conf

        curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
        sudo usermod -aG docker ubuntu

        TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
        PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
        PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
        K8S_ROLES="--etcd --controlplane"

        sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}
    1. Worker group: Nodes that will be part of the k8s worker plane. Worker nodes will be scaled by cluster-autoscaler using the ASG.

    • IAM profile: Provides cloud_provider worker integration. This profile is called K8sWorkerProfile.

      ```json
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

    • IAM role: K8sWorkerRole: [K8sWorkerProfile]

    • Security group: K8sWorkerSg More info at RKE ports (custom nodes tab)

    • Tags:

      • kubernetes.io/cluster/<clusterID>: owned
      • k8s.io/cluster-autoscaler/<clusterName>: true
      • k8s.io/cluster-autoscaler/enabled: true

    • User data: K8sWorkerUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add worker node to the k8s cluster

      #!/bin/bash -x

      cat <<EOF > /etc/sysctl.d/90-kubelet.conf
      vm.overcommit_memory = 1
      vm.panic_on_oom = 0
      kernel.panic = 10
      kernel.panic_on_oops = 1
      kernel.keys.root_maxkeys = 1000000
      kernel.keys.root_maxbytes = 25000000
      EOF
      sysctl -p /etc/sysctl.d/90-kubelet.conf

      curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
      sudo usermod -aG docker ubuntu

      TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
      PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
      PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
      K8S_ROLES="--worker"

      sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKCSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}

    More info is at RKE clusters on AWS and Cluster Autoscaler on AWS.

    3. Deploy Nodes​

    Once we've configured AWS, let's create VMs to bootstrap our cluster:

    • master (etcd+controlplane): Depending your needs, deploy three master instances with proper size. More info is at the recommendations for production-ready clusters.

      • IAM role: K8sMasterRole
      • Security group: K8sMasterSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
      • User data: K8sMasterUserData

    • worker: Define an ASG on EC2 with the following settings:

      • Name: K8sWorkerAsg
      • IAM role: K8sWorkerRole
      • Security group: K8sWorkerSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
        • k8s.io/cluster-autoscaler/<clusterName>: true
        • k8s.io/cluster-autoscaler/enabled: true
      • User data: K8sWorkerUserData
      • Instances:
        • minimum: 2
        • desired: 2
        • maximum: 10

    Once the VMs are deployed, you should have a Rancher custom cluster up and running with three master and two worker nodes.

    4. Install Cluster-autoscaler​

    At this point, we should have rancher cluster up and running. We are going to install cluster-autoscaler on master nodes and kube-system namespace, following cluster-autoscaler recommendation.

    Parameters​

    This table shows cluster-autoscaler parameters for fine tuning:

    ParameterDefaultDescription
    cluster-name-Autoscaled cluster name, if available
    address:8085The address to expose Prometheus metrics
    kubernetes-Kubernetes master location. Leave blank for default
    kubeconfig-Path to kubeconfig file with authorization and master location information
    cloud-config-The path to the cloud provider configuration file. Empty string for no configuration file
    namespace"kube-system"Namespace in which cluster-autoscaler run
    scale-down-enabledtrueShould CA scale down the cluster
    scale-down-delay-after-add"10m"How long after scale up that scale down evaluation resumes
    scale-down-delay-after-delete0How long after node deletion that scale down evaluation resumes, defaults to scanInterval
    scale-down-delay-after-failure"3m"How long after scale down failure that scale down evaluation resumes
    scale-down-unneeded-time"10m"How long a node should be unneeded before it is eligible for scale down
    scale-down-unready-time"20m"How long an unready node should be unneeded before it is eligible for scale down
    scale-down-utilization-threshold0.5Sum of cpu or memory of all pods running on the node divided by node's corresponding allocatable resource, below which a node can be considered for scale down
    scale-down-gpu-utilization-threshold0.5Sum of gpu requests of all pods running on the node divided by node's allocatable resource, below which a node can be considered for scale down
    scale-down-non-empty-candidates-count30Maximum number of non empty nodes considered in one iteration as candidates for scale down with drain
    scale-down-candidates-pool-ratio0.1A ratio of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    scale-down-candidates-pool-min-count50Minimum number of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    node-deletion-delay-timeout"2m"Maximum time CA waits for removing delay-deletion.cluster-autoscaler.kubernetes.io/ annotations before deleting the node
    scan-interval"10s"How often cluster is reevaluated for scale up or down
    max-nodes-total0Maximum number of nodes in all node groups. Cluster autoscaler will not grow the cluster beyond this number
    cores-total"0:320000"Minimum and maximum number of cores in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    memory-total"0:6400000"Minimum and maximum number of gigabytes of memory in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    cloud-provider-Cloud provider type
    max-bulk-soft-taint-count10Maximum number of nodes that can be tainted/untainted PreferNoSchedule at the same time. Set to 0 to turn off such tainting
    max-bulk-soft-taint-time"3s"Maximum duration of tainting/untainting nodes as PreferNoSchedule at the same time
    max-empty-bulk-delete10Maximum number of empty nodes that can be deleted at the same time
    max-graceful-termination-sec600Maximum number of seconds CA waits for pod termination when trying to scale down a node
    max-total-unready-percentage45Maximum percentage of unready nodes in the cluster. After this is exceeded, CA halts operations
    ok-total-unready-count3Number of allowed unready nodes, irrespective of max-total-unready-percentage
    scale-up-from-zerotrueShould CA scale up when there 0 ready nodes
    max-node-provision-time"15m"Maximum time CA waits for node to be provisioned
    nodes-sets min,max size and other configuration data for a node group in a format accepted by cloud provider. Can be used multiple times. Format: <min>:<max>:<other...>
    node-group-auto-discovery-One or more definition(s) of node group auto-discovery. A definition is expressed <name of discoverer>:[<key>[=<value>]]
    estimator-"binpacking"
    expander"random"Type of node group expander to be used in scale up. Available values: ["random","most-pods","least-waste","price","priority"]
    ignore-daemonsets-utilizationfalseShould CA ignore DaemonSet pods when calculating resource utilization for scaling down
    ignore-mirror-pods-utilizationfalseShould CA ignore Mirror pods when calculating resource utilization for scaling down
    write-status-configmaptrueShould CA write status information to a configmap
    max-inactivity"10m"Maximum time from last recorded autoscaler activity before automatic restart
    max-failing-time"15m"Maximum time from last recorded successful autoscaler run before automatic restart
    balance-similar-node-groupsfalseDetect similar node groups and balance the number of nodes between them
    node-autoprovisioning-enabledfalseShould CA autoprovision node groups when needed
    max-autoprovisioned-node-group-count15The maximum number of autoprovisioned groups in the cluster
    unremovable-node-recheck-timeout"5m"The timeout before we check again a node that couldn't be removed before
    expendable-pods-priority-cutoff-10Pods with priority below cutoff will be expendable. They can be killed without any consideration during scale down and they don't cause scale up. Pods with null priority (PodPriority disabled) are non expendable
    regionalfalseCluster is regional
    new-pod-scale-up-delay"0s"Pods less than this old will not be considered for scale-up
    ignore-taint-Specifies a taint to ignore in node templates when considering to scale a node group
    balancing-ignore-label-Specifies a label to ignore in addition to the basic and cloud-provider set of labels when comparing if two node groups are similar
    aws-use-static-instance-listfalseShould CA fetch instance types in runtime or use a static list. AWS only
    profilingfalseIs debug/pprof endpoint enabled

    Deployment​

    Based on cluster-autoscaler-run-on-master.yaml example, we've created our own cluster-autoscaler-deployment.yaml to use preferred auto-discovery setup, updating tolerations, nodeSelector, image version and command config:

    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
      name: cluster-autoscaler
      namespace: kube-system
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["events", "endpoints"]
        verbs: ["create", "patch"]
      - apiGroups: [""]
        resources: ["pods/eviction"]
        verbs: ["create"]
      - apiGroups: [""]
        resources: ["pods/status"]
        verbs: ["update"]
      - apiGroups: [""]
        resources: ["endpoints"]
        resourceNames: ["cluster-autoscaler"]
        verbs: ["get", "update"]
      - apiGroups: [""]
        resources: ["nodes"]
        verbs: ["watch", "list", "get", "update"]
      - apiGroups: [""]
        resources:
          - "pods"
          - "services"
          - "replicationcontrollers"
          - "persistentvolumeclaims"
          - "persistentvolumes"
        verbs: ["watch", "list", "get"]
      - apiGroups: ["extensions"]
        resources: ["replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["policy"]
        resources: ["poddisruptionbudgets"]
        verbs: ["watch", "list"]
      - apiGroups: ["apps"]
        resources: ["statefulsets", "replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["storage.k8s.io"]
        resources: ["storageclasses", "csinodes"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["batch", "extensions"]
        resources: ["jobs"]
        verbs: ["get", "list", "watch", "patch"]
      - apiGroups: ["coordination.k8s.io"]
        resources: ["leases"]
        verbs: ["create"]
      - apiGroups: ["coordination.k8s.io"]
        resourceNames: ["cluster-autoscaler"]
        resources: ["leases"]
        verbs: ["get", "update"]
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["configmaps"]
        verbs: ["create","list","watch"]
      - apiGroups: [""]
        resources: ["configmaps"]
        resourceNames: ["cluster-autoscaler-status", "cluster-autoscaler-priority-expander"]
        verbs: ["delete", "get", "update", "watch"]

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        app: cluster-autoscaler
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: cluster-autoscaler
      template:
        metadata:
          labels:
            app: cluster-autoscaler
          annotations:
            prometheus.io/scrape: 'true'
            prometheus.io/port: '8085'
        spec:
          serviceAccountName: cluster-autoscaler
          tolerations:
            - effect: NoSchedule
              operator: "Equal"
              value: "true"
              key: node-role.kubernetes.io/controlplane
          nodeSelector:
            node-role.kubernetes.io/controlplane: "true"
          containers:
            - image: eu.gcr.io/k8s-artifacts-prod/autoscaling/cluster-autoscaler:<VERSION>
              name: cluster-autoscaler
              resources:
                limits:
                  cpu: 100m
                  memory: 300Mi
                requests:
                  cpu: 100m
                  memory: 300Mi
              command:
                - ./cluster-autoscaler
                - --v=4
                - --stderrthreshold=info
                - --cloud-provider=aws
                - --skip-nodes-with-local-storage=false
                - --expander=least-waste
                - --node-group-auto-discovery=asg:tag=k8s.io/cluster-autoscaler/enabled,k8s.io/cluster-autoscaler/<clusterName>
              volumeMounts:
                - name: ssl-certs
                  mountPath: /etc/ssl/certs/ca-certificates.crt
                  readOnly: true
              imagePullPolicy: "Always"
          volumes:
            - name: ssl-certs
              hostPath:
                path: "/etc/ssl/certs/ca-certificates.crt"

    Once the manifest file is prepared, deploy it in the Kubernetes cluster (Rancher UI can be used instead):

    kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml
    note

    Cluster-autoscaler deployment can also be set up using manual configuration

    Testing

    At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage K8sWorkerAsg ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true:

    • There are pods that failed to run in the cluster due to insufficient resources. In this case, the cluster is scaled up.
    • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes. In this case, the cluster is scaled down.

    Generating Load​

    We've prepared a test-deployment.yaml just to generate load on the Kubernetes cluster and see if cluster-autoscaler is working properly. The test deployment is requesting 1000m CPU and 1024Mi memory by three replicas. Adjust the requested resources and/or replica to be sure you exhaust the Kubernetes cluster resources:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      labels:
        app: hello-world
      name: hello-world
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: hello-world
      strategy:
        rollingUpdate:
          maxSurge: 1
          maxUnavailable: 0
        type: RollingUpdate
      template:
        metadata:
          labels:
            app: hello-world
        spec:
          containers:
          - image: rancher/hello-world
            imagePullPolicy: Always
            name: hello-world
            ports:
            - containerPort: 80
              protocol: TCP
            resources:
              limits:
                cpu: 1000m
                memory: 1024Mi
              requests:
                cpu: 1000m
                memory: 1024Mi

    Once the test deployment is prepared, deploy it in the Kubernetes cluster default namespace (Rancher UI can be used instead):

    kubectl -n default apply -f test-deployment.yaml

    Checking Scale​

    Once the Kubernetes resources got exhausted, cluster-autoscaler should scale up worker nodes where pods failed to be scheduled. It should scale up until up until all pods became scheduled. You should see the new nodes on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Once scale up is checked, let check for scale down. To do it, reduce the replica number on the test deployment until you release enough Kubernetes cluster resources to scale down. You should see nodes disappear on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html b/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html index 9b77910b59b..393414fb4b3 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html @@ -5,13 +5,13 @@ Nodes and Node Pools | Rancher Manager - +
    Version: v2.6

    Nodes and Node Pools

    After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's Node tab. Depending on the option used to provision the cluster, there are different node options available.

    note

    If you want to manage the cluster and not individual nodes, see Editing Clusters.

    Node Options Available for Each Cluster Creation Option​

    The following table lists which node options are available for each type of cluster in Rancher. Click the links in the Option column for more detailed information about each feature.

    OptionNodes Hosted by an Infrastructure ProviderCustom NodeHosted ClusterRegistered EKS NodesAll Other Registered NodesDescription
    Cordon✓✓✓✓✓Marks the node as unschedulable.
    Drain✓✓✓✓✓Marks the node as unschedulable and evicts all pods.
    Edit✓✓✓✓✓Enter a custom name, description, label, or taints for a node.
    View API✓✓✓✓✓View API data.
    Delete✓✓**Deletes defective nodes from the cluster.
    Download Keys✓Download SSH key in order to SSH into the node.
    Node Scaling✓✓Scale the number of nodes in the node pool up or down.

    * Delete option accessible via View API

    Nodes Hosted by an Infrastructure Provider​

    Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are hosted in an infrastructure provider.

    Clusters provisioned using one of the node pool options can be scaled up or down if the node pool is edited.

    A node pool can also automatically maintain the node scale that's set during the initial cluster provisioning if node auto-replace is enabled. This scale determines the number of active nodes that Rancher maintains for the cluster.

    Rancher uses node templates to replace nodes in the node pool. Each node template uses cloud provider credentials to allow Rancher to set up the node in the infrastructure provider.

    Nodes Provisioned by Hosted Kubernetes Providers​

    Options for managing nodes hosted by a Kubernetes provider are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly.

    Registered Nodes​

    Although you can deploy workloads to a registered cluster using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher.

    Managing and Editing Individual Nodes​

    Editing a node lets you:

    • Change its name
    • Change its description
    • Add labels
    • Add/Remove taints

    To manage individual nodes, browse to the cluster that you want to manage and then select Nodes from the main menu. You can open the options menu for a node by clicking its ⋮ icon (...).

    Viewing a Node in the Rancher API​

    Select this option to view the node's API endpoints.

    Deleting a Node​

    Use Delete to remove defective nodes from the cloud provider.

    When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and node auto-replace is enabled.

    tip

    If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, scale down rather than delete.

    Scaling Nodes​

    For nodes hosted by an infrastructure provider, you can scale the number of nodes in each node pool by using the scale controls. This option isn't available for other cluster types.

    SSH into a Node Hosted by an Infrastructure Provider​

    For nodes hosted by an infrastructure provider, you have the option of downloading its SSH key so that you can connect to it remotely from your desktop.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to SSH into a node and click the name of the cluster.

    3. On the Machine Pools tab, find the node that you want to remote into and click ⋮ > Download SSH Key. A ZIP file containing files used for SSH will be downloaded.

    4. Extract the ZIP file to any location.

    5. Open Terminal. Change your location to the extracted ZIP file.

    6. Enter the following command:

      ssh -i id_rsa root@<IP_OF_HOST>

    Cordoning a Node​

    Cordoning a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.

    Draining a Node​

    Draining is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.

    • For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.

    • For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.

    You can drain nodes that are in either a cordoned or active state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods.

    However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value.

    Aggressive and Safe Draining Options​

    When you configure the upgrade strategy for the cluster, you will be able to enable node draining. If node draining is enabled, you will be able to configure how pods are deleted and rescheduled.

    • Aggressive Mode

      In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.

      Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.

    • Safe Mode

      If a node has standalone pods or ephemeral data it will be cordoned but not drained.

    Grace Period​

    The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.

    Timeout​

    The amount of time drain should continue to wait before giving up.

    Kubernetes Known Issue:

    The timeout setting was not enforced while draining a node before Kubernetes 1.12.

    Drained and Cordoned State​

    If there's any error related to user input, the node enters a cordoned state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.

    If the drain continues without error, the node enters a draining state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to cordoned.

    Once drain successfully completes, the node will be in a state of drained. You can then power off or delete the node.

    Want to know more about cordon and drain? See the Kubernetes documentation.

    Labeling a Node to be Ignored by Rancher​

    Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.

    Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.

    In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.

    You can label nodes to be ignored by using a setting in the Rancher UI, or by using kubectl.

    note

    There is an open issue in which nodes labeled to be ignored can get stuck in an updating state.

    Labeling Nodes to be Ignored with kubectl​

    To add a node that will be ignored by Rancher, use kubectl to create a node that has the following label:

    cattle.rancher.io/node-status: ignore

    Result: If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with kubectl.

    If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.

    If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.

    If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the nodeName is listed in the Rancher settings in the Rancher API under v3/settings/ignore-node-name.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html b/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html index afb95643eac..e6ecf2b1940 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html @@ -5,13 +5,13 @@ Projects and Kubernetes Namespaces with Rancher | Rancher Manager - +
    Version: v2.6

    Projects and Kubernetes Namespaces with Rancher

    A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas.

    A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    note

    As of Rancher v2.6, projects are de-emphasized on the UI because it is no longer required to create any Kubernetes resources within a project scope. However, resources such as Secrets can still be created in a project scope if the legacy feature flag is enabled.

    This section describes how projects and namespaces work with Rancher.

    About Namespaces​

    A namespace is a concept introduced by Kubernetes. According to the official Kubernetes documentation on namespaces,

    note

    Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all.

    Namespaces provide the following functionality:

    • Providing a scope for names: Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace.
    • Resource quotas: Namespaces provide a way to divide cluster resources between multiple users.

    You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace.

    You can assign the following resources directly to namespaces:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    For more information on creating and moving namespaces, see Namespaces.

    Role-based access control issues with namespaces and kubectl​

    Because projects are a concept introduced by Rancher, kubectl does not have the capability to restrict the creation of namespaces to a project the creator has access to.

    This means that when standard users with project-scoped permissions create a namespaces with kubectl, it may be unusable because kubectl doesn't require the new namespace to be scoped within a certain project.

    If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    If a standard user is a project owner, the user will be able to create namespaces within that project. The Rancher UI will prevent that user from creating namespaces outside the scope of the projects they have access to.

    About Projects​

    In terms of hierarchy:

    • Clusters contain projects
    • Projects contain namespaces

    You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    In the base version of Kubernetes, features like role-based access rights or cluster resources are assigned to individual namespaces. A project allows you to save time by giving an individual or a team access to multiple namespaces simultaneously.

    You can use projects to perform actions such as:

    • Assign users to a group of namespaces (i.e., project membership).
    • Assign users specific roles in a project. A role can be owner, member, read-only, or custom.
    • Assign resources to the project.
    • Assign Pod Security Policies.

    When you create a cluster, two projects are automatically created within it:

    The Cluster's Default Project​

    When you provision a cluster with Rancher, it automatically creates a default project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.

    If you don't have a need for more than the default namespace, you also do not need more than the Default project in Rancher.

    If you require another level of organization beyond the Default project, you can create more projects in Rancher to isolate namespaces, applications and resources.

    The System Project​

    When troubleshooting, you can view the system project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers.

    To open it, open the cluster view and click Cluster > Projects/Namespaces. This view shows all of the namespaces in the system project.

    The system project:

    • Is automatically created when you provision a cluster.
    • Lists all namespaces that exist in v3/settings/system-namespaces, if they exist.
    • Allows you to add more namespaces or move its namespaces to other projects.
    • Cannot be deleted because it's required for cluster operations.
    note

    In RKE clusters where the project network isolation option is enabled, the system project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.

    Project Authorization​

    Standard users are only authorized for project access in two situations:

    • An administrator, cluster owner or cluster member explicitly adds the standard user to the project's Members tab.
    • Standard users can access projects that they create themselves.

    Pod Security Policies​

    Rancher extends Kubernetes to allow the application of Pod Security Policies at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level.

    Creating Projects​

    This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.

    1. Name a new project.
    2. Optional: Select a pod security policy.
    3. Recommended: Add project members.
    4. Optional: Add resource quotas.

    1. Name a New Project​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster you want to project in and click Explore.
    3. Click Cluster > Projects/Namespaces.
    4. Click Create Project.
    5. Enter a Project Name.

    2. Optional: Select a Pod Security Policy​

    This option is only available if you've already created a Pod Security Policy. For instruction, see Creating Pod Security Policies.

    Assigning a PSP to a project will:

    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.

    Use the Members section to provide other users with project access and roles.

    By default, your user is added as the project Owner.

    Notes on Permissions:

    • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Choose Custom to create a custom role on the fly: Custom Project Roles.

    To add members:

    1. In the Members tab, click Add.
    2. From the Select Member field, search for a user or group that you want to assign project access. Note: You can only search for groups if external authentication is enabled.
    3. In the Project Permissions section, choose a role. For more information, refer to the documentation on project roles.

    4. Optional: Add Resource Quotas​

    Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see Resource Quotas.

    To add a resource quota,

    1. In the Resource Quotas tab, click Add Resource.
    2. Select a Resource Type. For more information, see Resource Quotas..
    3. Enter values for the Project Limit and the Namespace Default Limit.
    4. Optional: Specify Container Default Resource Limit, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see Container Default Resource Limit
    5. Click Create.

    Result: Your project is created. You can view it from the cluster's Projects/Namespaces view.

    FieldDescription
    Project LimitThe overall resource limit for the project.
    Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html b/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html index e1af4e2ef82..0df09154305 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html @@ -5,13 +5,13 @@ Certificate Rotation | Rancher Manager - +
    Version: v2.6

    Certificate Rotation

    caution

    Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window.

    By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted.

    Certificates can be rotated for the following services:

    • etcd
    • kubelet (node certificate)
    • kubelet (serving certificate, if enabled)
    • kube-apiserver
    • kube-proxy
    • kube-scheduler
    • kube-controller-manager
    note

    For users who didn't rotate their webhook certificates, and they have expired after one year, please see this page for help.

    Certificate Rotation​

    Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster you want to rotate certificates for amd click ⋮ > Rotate Certificates.

    3. Select which certificates that you want to rotate.

      • Rotate all Service certificates (keep the same CA)
      • Rotate an individual service and choose one of the services from the drop-down menu

    4. Click Save.

    Results: The selected certificates will be rotated and the related services will be restarted to start using the new certificate.

    Additional Notes​

    Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher launched Kubernetes clusters.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-clusters/rotate-encryption-key.html b/how-to-guides/advanced-user-guides/manage-clusters/rotate-encryption-key.html index eaf23275a29..dabae21a0b3 100644 --- a/how-to-guides/advanced-user-guides/manage-clusters/rotate-encryption-key.html +++ b/how-to-guides/advanced-user-guides/manage-clusters/rotate-encryption-key.html @@ -5,13 +5,13 @@ Encryption Key Rotation | Rancher Manager - +
    Version: v2.6

    Encryption Key Rotation

    RKE1 Encryption Key Rotation​

    1. Enable encryption key rotation with either of the following two options:

      • Select the Enabled radio button in the Rancher UI under Cluster Options > Advanced Options > Secrets Encryption:

      Enable Encryption Key Rotation

      • OR, apply the following YAML:
      rancher_kubernetes_engine_config:
        services:
          kube_api:
            secrets_encryption_config:
              enabled: true

    2. Rotate keys in the Rancher UI:

      2.1. Click ☰ > Cluster Management.

      2.2. Select ⋮ > Rotate Encryption Keys on the far right of the screen next to your chosen cluster:

      Encryption Key Rotation

    RKE2 Encryption Key Rotation​

    New in v2.6.7

    Important: Encryption key rotation is enabled by default and cannot be disabled.

    To rotate keys in the Rancher UI:

    1. Click ☰ > Cluster Management.

    2. Select ⋮ > Rotate Encryption Keys on the far right of the screen next to your chosen cluster:

      Encryption Key Rotation

    Note: For more information on RKE2 secrets encryption config, please see the RKE2 docs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html b/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html index 1d4aaef5c84..601ebeef593 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html +++ b/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html @@ -5,13 +5,13 @@ Adding Users to Projects | Rancher Manager - +
    Version: v2.6

    Adding Users to Projects

    If you want to provide a user with access and permissions to specific projects and resources within a cluster, assign the user a project membership.

    You can add members to a project as it is created, or add them to an existing project.

    tip

    Want to provide a user with access to all projects within a cluster? See Adding Cluster Members instead.

    Adding Members to a New Project​

    You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the cluster administration section.

    Adding Members to an Existing Project​

    Following project creation, you can add users as project members so that they can access its resources.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to add members to a project and click Explore.

    3. Click Cluster > Projects/Namespaces.

    4. Go to the project where you want to add members and click ⋮ > Edit Config.

    5. In the Members tab, click Add.

    6. Search for the user or group that you want to add to the project.

      If external authentication is configured:

      • Rancher returns users from your external authentication source as you type.

      • A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in.

      note

      If you are logged in as a local user, external users do not display in your search results.

    7. Assign the user or group Project roles.

      What are Project Roles?

      Notes:

      • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create or delete namespaces in other projects they're assigned to, even with only the Read Only role assigned.

      • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

      • For Custom roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the project.

    • To revoke project membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html b/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html index c224549daf7..5273b0ff5a1 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html +++ b/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html @@ -5,13 +5,13 @@ Rancher's CI/CD Pipelines | Rancher Manager - +
    Version: v2.6

    Rancher's CI/CD Pipelines

    Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

    After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

    • Build your application from code to image.
    • Validate your builds.
    • Deploy your build images to your cluster.
    • Run unit tests.
    • Run regression tests.

    For details, refer to the pipelines section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html b/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html index c19a337480c..ce479859fb2 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html @@ -5,13 +5,13 @@ Namespaces | Rancher Manager - +
    Version: v2.6

    Namespaces

    Within Rancher, you can further divide projects into different namespaces, which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the default namespace, you can use multiple namespaces to isolate applications and resources.

    Although you assign resources at the project level so that each namespace in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace.

    Resources that you can assign directly to namespaces include:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    note

    If you create a namespace with kubectl, it may be unusable because kubectl doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    Creating Namespaces​

    Create a new namespace to isolate apps and resources in a project.

    tip

    When working with project resources that you can assign to a namespace (i.e., workloads, certificates, ConfigMaps, etc.) you can create a namespace on the fly.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to create a namespace and click Explore.

    3. Click Cluster > Projects/Namespaces.

    4. Go to the project where you want to add a namespace and click Create Namespace. Alternately, go to Not in a Project to create a namespace not associated with a project.

    5. Optional: If your project has Resource Quotas in effect, you can override the default resource Limits (which places a cap on the resources that the namespace can consume).

    6. Enter a Name and then click Create.

    Result: Your namespace is added to the project. You can begin assigning cluster resources to the namespace.

    Moving Namespaces to Another Project​

    Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to move a namespace and click Explore.

    3. Click Cluster > Projects/Namespaces.

    4. Go to the namespace you want to move and click ⋮ > Move.

    5. Select the namespace(s) that you want to move to a different project. Then click Move. You can move multiple namespaces at one.

      Notes:
      • Don't move the namespaces in the System project. Moving these namespaces can adversely affect cluster networking.
      • You cannot move a namespace into a project that already has a resource quotaconfigured.
      • If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace.

    6. Choose a new project for the new namespace and then click Move. Alternatively, you can remove the namespace from all projects by selecting None.

    Result: Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project.

    Editing Namespace Resource Quotas​

    You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    For more information, see how to edit namespace resource quotas.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html b/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html index ecd4e583816..b924739af31 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html @@ -5,14 +5,14 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.6

    Pod Security Policies

    note

    These cluster options are only available for clusters in which Rancher has launched Kubernetes.

    You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.

    Prerequisites​

    Applying a Pod Security Policy​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to move a namespace and click Explore.
    3. Click Cluster > Projects/Namespaces.
    4. Find the project that you want to add a PSP to. From that project, select ⋮ > Edit Config.
    5. From the Pod Security Policy drop-down, select the PSP you want to apply to the project. Assigning a PSP to a project will:
    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.
    1. Click Save.

    Result: The PSP is applied to the project and any namespaces added to the project.

    note

    Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html index 8fba9f2bbee..dcbfc9caea8 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html @@ -5,7 +5,7 @@ How Resource Quotas Work in Rancher Projects | Rancher Manager - + @@ -17,7 +17,7 @@ will assign a resource quota that has a zero amount for any res requested quota limit, use the field.cattle.io/resourceQuota annotation.

    Note that Rancher will only override limits for resources that are defined on the project quota.

    apiVersion: v1
    kind: Namespace
    metadata:
      annotations:
        field.cattle.io/projectId: [your-cluster-ID]:[your-project-ID]
        field.cattle.io/resourceQuota: '{"limit":{"limitsCpu":"100m", "configMaps": "50"}}'
      name: my-ns

    In this example, if the project's quota does not include configMaps in its list of resources, then Rancher will ignore configMaps in this override.

    Users are advised to create dedicated ResourceQuota objects in namespaces to configure additional custom limits for resources not defined on the project. Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, thus giving users more control.

    The following table explains the key differences between the two quota types.

    Rancher Resource QuotasKubernetes Resource Quotas
    Applies to projects and namespace.Applies to namespaces only.
    Creates resource pool for all namespaces in project.Applies static resource limits to individual namespaces.
    Applies resource quotas to namespaces through propagation.Applies only to the assigned namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html index dfbd16bac04..46d6e327bd0 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html @@ -5,13 +5,13 @@ Overriding the Default Limit for a Namespace | Rancher Manager - +
    Version: v2.6

    Overriding the Default Limit for a Namespace

    Although the Namespace Default Limit propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace.

    In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for Namespace 3 so that it has more resources available. Therefore, the administrator raises the namespace limits for Namespace 3 so that the namespace can access more resources.

    Namespace Default Limit Override

    Namespace Default Limit Override

    How to: Editing Namespace Resource Quotas

    Editing Namespace Resource Quotas​

    If there is a resource quota configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to edit a namespace resource quota and click Explore.

    3. Click Cluster > Projects/Namespaces.

    4. Find the namespace for which you want to edit the resource quota. Click ⋮ > Edit Config.

    5. Edit the resource limits. These limits determine the resources available to the namespace. The limits must be set within the configured project limits.

      For more information about each Resource Type, see the type reference.

      note
      • If a resource quota is not configured for the project, these options will not be available.
      • If you enter limits that exceed the configured project limits, Rancher will not let you save your edits.

    Result: Your override is applied to the namespace's resource quota.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html index bd335ea1ea3..2d189942050 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html @@ -5,13 +5,13 @@ Resource Quota Type Reference | Rancher Manager - +
    Version: v2.6

    Resource Quota Type Reference

    When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types.

    Resource TypeDescription
    CPU Limit*The maximum amount of CPU (in millicores) allocated to the project/namespace.1
    CPU Reservation*The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1
    Memory Limit*The maximum amount of memory (in bytes) allocated to the project/namespace.1
    Memory Reservation*The minimum amount of memory (in bytes) guaranteed to the project/namespace.1
    Storage ReservationThe minimum amount of storage (in gigabytes) guaranteed to the project/namespace.
    Services Load BalancersThe maximum number of load balancers services that can exist in the project/namespace.
    Services Node PortsThe maximum number of node port services that can exist in the project/namespace.
    PodsThe maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of .status.phase in (Failed, Succeeded) equal to true).
    ServicesThe maximum number of services that can exist in the project/namespace.
    ConfigMapsThe maximum number of ConfigMaps that can exist in the project/namespace.
    Persistent Volume ClaimsThe maximum number of persistent volume claims that can exist in the project/namespace.
    Replications ControllersThe maximum number of replication controllers that can exist in the project/namespace.
    SecretsThe maximum number of secrets that can exist in the project/namespace.
    *

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the Kubernetes documentation for more details on why this is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html index 18f330e16f7..4d549e55748 100644 --- a/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html +++ b/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html @@ -5,13 +5,13 @@ Setting Container Default Resource Limits | Rancher Manager - +
    Version: v2.6

    Setting Container Default Resource Limits

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the Kubernetes documentation for more details on why this is required.

    To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    Editing the Container Default Resource Limit​

    Edit the container default resource limit when:

    • You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container.
    • You want to edit the default container resource limit.
    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to edit the default resource limit and click Explore.
    3. Click Cluster > Projects/Namespaces.
    4. Find the project that you want to edit the container default resource limit. From that project, select ⋮ > Edit Config.
    5. Expand Container Default Resource Limit and edit the values.

    Resource Limit Propagation​

    When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers.

    You can set a default container resource limit on a project and launch any catalog applications.

    Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation.

    Container Resource Quota Types​

    The following resource limits can be configured:

    Resource TypeDescription
    CPU LimitThe maximum amount of CPU (in millicores) allocated to the container.
    CPU ReservationThe minimum amount of CPU (in millicores) guaranteed to the container.
    Memory LimitThe maximum amount of memory (in bytes) allocated to the container.
    Memory ReservationThe minimum amount of memory (in bytes) guaranteed to the container.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html index 66d5b328f0e..6fed201624a 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html @@ -5,13 +5,13 @@ Persistent Grafana Dashboards | Rancher Manager - +
    Version: v2.6

    Persistent Grafana Dashboards

    To allow the Grafana dashboard to persist after the Grafana instance restarts, add the dashboard configuration JSON into a ConfigMap. ConfigMaps also allow the dashboards to be deployed with a GitOps or CD based approach. This allows the dashboard to be put under version control.

    Creating a Persistent Grafana Dashboard

    Prerequisites:
    • The monitoring application needs to be installed.
    • To create the persistent dashboard, you must have at least the Manage Config Maps Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the monitoring-dashboard-edit or monitoring-dashboard-admin Kubernetes native RBAC Roles exposed by the Monitoring chart.
    • To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a project-member role.

    1. Get the JSON model of the dashboard that you want to persist​

    To create a persistent dashboard, you will need to get the JSON model of the dashboard you want to persist. You can use a premade dashboard or build your own.

    To use a premade dashboard, go to https://grafana.com/grafana/dashboards, open up its detail page, and click on the Download JSON button to get the JSON model for the next step.

    To use your own dashboard:

    1. Click on the link to open Grafana. On the cluster detail page, click Monitoring.

    2. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is admin/prom-operator. Alternative credentials can also be supplied on deploying or upgrading the chart.

      note

      Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart.

    3. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click JSON Model.

    4. Copy the JSON data structure that appears.

    2. Create a ConfigMap using the Grafana JSON model​

    Create a ConfigMap in the namespace that contains your Grafana Dashboards (e.g. cattle-dashboards by default).

    The ConfigMap should look like this:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      labels:
        grafana_dashboard: "1"
      name: <dashboard-name>
      namespace: cattle-dashboards # Change if using a non-default namespace
    data:
      <dashboard-name>.json: |-
        <copied-json>

    By default, Grafana is configured to watch all ConfigMaps with the grafana_dashboard label within the cattle-dashboards namespace.

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, refer to this section.

    To create the ConfigMap in the Rancher UI,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to see the visualizations and click Explore.
    3. Click More Resources > Core > ConfigMaps.
    4. Click Create.
    5. Set up the key-value pairs similar to the example above. When entering the value for <dashboard-name>.json, click Read from File to upload the JSON data model as the value.
    6. Click Create.

    Result: After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted.

    Dashboards that are persisted using ConfigMaps cannot be deleted or edited from the Grafana UI.

    If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap.

    Configuring Namespaces for the Grafana Dashboard ConfigMap​

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the rancher-monitoring Helm chart:

    grafana.sidecar.dashboards.searchNamespace=ALL

    Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in grafana.dashboards.namespace, which defaults to cattle-dashboards.

    Known Issues

    For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation helm.sh/resource-policy: "keep".

    This annotation will be added by default in the new monitoring chart released by Rancher v2.5.8, but it still needs to be manually applied for users of earlier Rancher versions.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html index dd68cbaa3f5..6baf9736196 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html @@ -5,13 +5,13 @@ Customizing Grafana Dashboards | Rancher Manager - +
    Version: v2.6

    Customizing Grafana Dashboards

    In this section, you'll learn how to customize the Grafana dashboard to show metrics that apply to a certain container.

    Prerequisites​

    Before you can customize a Grafana dashboard, the rancher-monitoring application must be installed.

    To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a project-member role.

    Signing in to Grafana​

    1. In the Rancher UI, go to the cluster that has the dashboard you want to customize.
    2. In the left navigation menu, click Monitoring.
    3. Click Grafana. The Grafana dashboard should open in a new tab.
    4. Go to the log in icon in the lower left corner and click Sign In.
    5. Log in to Grafana. The default Admin username and password for the Grafana instance is admin/prom-operator. (Regardless of who has the password, cluster administrator permission in Rancher is still required access the Grafana instance.) Alternative credentials can also be supplied on deploying or upgrading the chart.

    Getting the PromQL Query Powering a Grafana Panel​

    For any panel, you can click the title and click Explore to get the PromQL queries powering the graphic.

    For this example, we would like to get the CPU usage for the Alertmanager container, so we click CPU Utilization > Inspect.

    The Data tab shows the underlying data as a time series, with the time in first column and the PromQL query result in the second column. Copy the PromQL query.

    (1 - (avg(irate({__name__=~"node_cpu_seconds_total|windows_cpu_time_total",mode="idle"}[5m])))) * 100

    You can then modify the query in the Grafana panel or create a new Grafana panel using the query.

    See also:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html index fb9ee86f318..1e654e4080c 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html @@ -5,13 +5,13 @@ Debugging High Memory Usage | Rancher Manager - +
    Version: v2.6

    Debugging High Memory Usage

    Every time series in Prometheus is uniquely identified by its metric name and optional key-value pairs called labels.

    The labels allow the ability to filter and aggregate the time series data, but they also multiply the amount of data that Prometheus collects.

    Each time series has a defined set of labels, and Prometheus generates a new time series for all unique combinations of labels. If a metric has two labels attached, two time series are generated for that metric. Changing any label value, including adding or removing a label, will create a new time series.

    Prometheus is optimized to store data that is index-based on series. It is designed for a relatively consistent number of time series and a relatively large number of samples that need to be collected from the exporters over time.

    Inversely, Prometheus is not optimized to accommodate a rapidly changing number of time series. For that reason, large bursts of memory usage can occur when monitoring is installed on clusters where many resources are being created and destroyed, especially on multi-tenant clusters.

    Reducing Memory Bursts​

    To reduce memory consumption, Prometheus can be configured to store fewer time series, by scraping fewer metrics or by attaching fewer labels to the time series. To see which series use the most memory, you can check the TSDB (time series database) status page in the Prometheus UI.

    Distributed Prometheus solutions such as Thanos and Cortex use an alternate architecture in which multiple small Prometheus instances are deployed. In the case of Thanos, the metrics from each Prometheus are aggregated into the common Thanos deployment, and then those metrics are exported to a persistent store, such as S3. This more robust architecture avoids burdening any single Prometheus instance with too many time series, while also preserving the ability to query metrics on a global level.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html index 180d9c2ba5c..9bb89f85db8 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html @@ -5,13 +5,13 @@ Enable Monitoring | Rancher Manager - +
    Version: v2.6

    Enable Monitoring

    As an administrator or cluster owner, you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.

    This page describes how to enable monitoring and alerting within a cluster using the new monitoring application.

    You can enable monitoring with or without SSL.

    Requirements

    • Make sure that you are allowing traffic on port 9796 for each of your nodes because Prometheus will scrape metrics from here.
    • Make sure your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. A breakdown of the resource limits and requests is here.
    • When installing monitoring on an RKE cluster using RancherOS or Flatcar Linux nodes, change the etcd node certificate directory to /opt/rke/etc/kubernetes/ssl.
    • For clusters provisioned with the RKE CLI and the address is set to a hostname instead of an IP address, set rkeEtcd.clients.useLocalhost to true during the Values configuration step of the installation. The YAML snippet will look like the following:
    rkeEtcd:
      clients:
        useLocalhost: true
    note

    If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment.

    Setting Resource Limits and Requests

    The resource requests and limits can be configured when installing rancher-monitoring. To configure Prometheus resources from the Rancher UI, click Apps & Marketplace > Monitoring in the upper left corner.

    For more information about the default limits, see this page.

    Install the Monitoring Application

    Enable Monitoring for use without SSL​

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. Click Cluster Tools (bottom left corner).
    4. Click Install by Monitoring.
    5. Optional: Customize requests, limits and more for Alerting, Prometheus, and Grafana in the Values step. For help, refer to the configuration reference.

    Result: The monitoring app is deployed in the cattle-monitoring-system namespace.

    Enable Monitoring for use with SSL​

    1. Follow the steps on this page to create a secret in order for SSL to be used for alerts.
    • The secret should be created in the cattle-monitoring-system namespace. If it doesn't exist, create it first.
    • Add the ca, cert, and key files to the secret.
    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to enable monitoring for use with SSL and click Explore.
    3. Click Apps & Marketplace > Charts.
    4. Click Monitoring.
    5. Click Install or Update, depending on whether you have already installed Monitoring.
    6. Check the box for Customize Helm options before install and click Next.
    7. Click Alerting.
    8. In the Additional Secrets field, add the secrets created earlier.

    Result: The monitoring app is deployed in the cattle-monitoring-system namespace.

    When creating a receiver, SSL-enabled receivers such as email or webhook will have a SSL section with fields for CA File Path, Cert File Path, and Key File Path. Fill in these fields with the paths to each of ca, cert, and key. The path will be of the form /etc/alertmanager/secrets/name-of-file-in-secret.

    For example, if you created a secret with these key-value pairs:

    ca.crt=`base64-content`
    cert.pem=`base64-content`
    key.pfx=`base64-content`

    Then Cert File Path would be set to /etc/alertmanager/secrets/cert.pem.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html index 0dd1ba505ce..3b49591d2ce 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html @@ -5,14 +5,14 @@ Migrating to Rancher v2.5+ Monitoring | Rancher Manager - +
    Version: v2.6

    Migrating to Rancher v2.5+ Monitoring

    If you previously enabled Monitoring, Alerting, or Notifiers in Rancher before v2.5, there is no automatic upgrade path for switching to the new monitoring/alerting solution. Before deploying the new monitoring solution via Cluster Explore, you will need to disable and remove all existing custom alerts, notifiers and monitoring installations for the whole cluster and in all projects.

    Monitoring Before Rancher v2.5​

    As of v2.2.0, the global view in the legacy Rancher UI allowed users to enable Monitoring & Alerting V1 (both powered by Prometheus Operator) independently within a cluster.

    When Monitoring is enabled, Monitoring V1 deploys Prometheus and Grafana onto a cluster to monitor the state of processes of your cluster nodes, Kubernetes components, and software deployments and create custom dashboards to make it easy to visualize collected metrics.

    Monitoring V1 could be configured on both a cluster-level and on a project-level and would automatically scrape certain workloads deployed as Apps on the Rancher cluster.

    When Alerts or Notifiers are enabled, Alerting V1 deploys Prometheus Alertmanager and a set of Rancher controllers onto a cluster that allows users to define alerts and configure alert-based notifications via Email, Slack, PagerDuty, etc. Users can choose to create different types of alerts depending on what needs to be monitored (e.g. System Services, Resources, CIS Scans, etc.); however, PromQL Expression-based alerts can only be created if Monitoring V1 is enabled.

    Monitoring and Alerting via Cluster Explorer in Rancher 2.5​

    As of v2.5.0, Rancher's Cluster Explorer now allows users to enable Monitoring & Alerting V2 (both powered by Prometheus Operator) together within a cluster.

    Unlike in Monitoring & Alerting V1, both features are packaged in a single Helm chart found here. The behavior of this chart and configurable fields closely matches kube-prometheus-stack, a Prometheus Community Helm chart, and any deviations from the upstream chart can be found in the CHANGELOG.md maintained with the chart.

    Monitoring V2 can only be configured on the cluster level. Project-level monitoring and alerting is no longer supported.

    For more information on how to configure Monitoring & Alerting V2, see this page.

    Changes to Role-based Access Control​

    Project owners and members no longer get access to Grafana or Prometheus by default. If view-only users had access to Grafana, they would be able to see data from any namespace. For Kiali, any user can edit things they don’t own in any namespace.

    For more information about role-based access control in rancher-monitoring, refer to this page.

    Migrating from Monitoring V1 to Monitoring V2​

    While there is no automatic migration available, it is possible to manually migrate custom Grafana dashboards and alerts that were created in Monitoring V1 to Monitoring V2.

    Before you can install Monitoring V2, Monitoring V1 needs to be uninstalled completely. In order to uninstall Monitoring V1:

    • Remove all cluster and project specific alerts and alerts groups.
    • Remove all notifiers.
    • Disable all project monitoring installations under Cluster -> Project -> Tools -> Monitoring.
    • Ensure that all project-monitoring apps in all projects have been removed and are not recreated after a few minutes
    • Disable the cluster monitoring installation under Cluster -> Tools -> Monitoring.
    • Ensure that the cluster-monitoring app and the monitoring-operator app in the System project have been removed and are not recreated after a few minutes.

    RKE Template Clusters​

    To prevent V1 monitoring from being re-enabled, disable monitoring and in future RKE template revisions via modification of the RKE template yaml:

    enable_cluster_alerting: false
    enable_cluster_monitoring: false

    Migrating Grafana Dashboards​

    You can migrate any dashboard added to Grafana in Monitoring V1 to Monitoring V2. In Monitoring V1 you can export an existing dashboard like this:

    • Sign into Grafana
    • Navigate to the dashboard you want to export
    • Go to the dashboard settings
    • Copy the JSON Model

    In the JSON Model, change all datasource fields from RANCHER_MONITORING to Prometheus. You can easily do this by replacing all occurrences of "datasource": "RANCHER_MONITORING" with "datasource": "Prometheus".

    If Grafana is backed by a persistent volume, you can now import this JSON Model into the Monitoring V2 Grafana UI. It is recommended to provide the dashboard to Grafana with a ConfigMap in the cattle-dashboards namespace that has the label grafana_dashboard: "1":

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: custom-dashboard
      namespace: cattle-dashboards
      labels:
        grafana_dashboard: "1"
    data:
      custom-dashboard.json: |
        {
          ...
        }

    Once this ConfigMap is created, the dashboard will automatically be added to Grafana.

    Migrating Alerts​

    It is only possible to directly migrate expression-based alerts to Monitoring V2. Fortunately, the event-based alerts that could be set up to alert on system component, node or workload events, are already covered out-of-the-box by the alerts that are part of Monitoring V2. So it is not necessary to migrate them.

    To migrate the following expression alert

    you have to either create a PrometheusRule configuration like this in any namespace

    apiVersion: monitoring.coreos.com/v1
    kind: PrometheusRule
    metadata:
      name: custom-rules
      namespace: default
    spec:
      groups:
        - name: custom.rules
          rules:
            - alert: Custom Expression Alert
              expr: prometheus_query > 5
              for: 5m
              labels:
                severity: critical
              annotations:
                summary: "The result of prometheus_query has been larger than 5 for 5m. Current value {{ $value }}"

    or add the Prometheus Rule through the Cluster Explorer

    For more details on how to configure PrometheusRules in Monitoring V2 see Monitoring Configuration.

    Migrating Notifiers​

    There is no direct equivalent for how notifiers work in Monitoring V1. Instead you have to replicate the desired setup with Routes and Receivers in Monitoring V2.

    Migrating for RKE Template Users​

    If the cluster is managed using an RKE template, you will need to disable monitoring in future RKE template revisions to prevent legacy monitoring from being re-enabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.html index 25a617bff4a..2ce36dafaf2 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/customize-grafana-dashboards.html @@ -5,13 +5,13 @@ Customizing Grafana Dashboards | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.html index 07577a487e9..b9c57dc46f0 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/enable-prometheus-federator.html @@ -5,13 +5,13 @@ Enable Prometheus Federator | Rancher Manager - +
    Version: v2.6

    Enable Prometheus Federator

    Requirements​

    By default, Prometheus Federator is configured and intended to be deployed alongside rancher-monitoring, which deploys Prometheus Operator alongside a Cluster Prometheus that each Project Monitoring Stack is configured to federate namespace-scoped metrics from by default.

    For instructions on installing rancher-monitoring, refer to this page.

    The default configuration should already be compatible with your rancher-monitoring stack. However, to optimize the security and usability of Prometheus Federator in your cluster, we recommend making these additional configurations to rancher-monitoring:

    Ensure the cattle-monitoring-system namespace is placed into the System Project (or a similarly locked down Project that has access to other Projects in the cluster)​

    Select Projects-Namespaces

    Prometheus Operator's security model expects that the namespace it is deployed into (e.g., cattle-monitoring-system) has limited access for anyone except Cluster Admins to avoid privilege escalation via execing into Pods (such as the Jobs executing Helm operations). In addition, deploying Prometheus Federator and all Project Prometheus stacks into the System Project ensures that each Project Prometheus is able to reach out to scrape workloads across all Projects, even if Network Policies are defined via Project Network Isolation. It also provides limited access for Project Owners, Project Members, and other users so that they're unable to access data that they shouldn't have access to (i.e., being allowed to exec into pods, set up the ability to scrape namespaces outside of a given Project, etc.).

    1. Open the System project to check your namespaces:

      Click Cluster > Projects/Namespaces in the Rancher UI. This will display all of the namespaces in the System project:

      Select Projects-Namespaces

    2. If you have an existing Monitoring V2 installation within the cattle-monitoring-system namespace, but that namespace is not in the System project, you may move the cattle-monitoring-system namespace into the System project or into another project of limited access. To do so, you may either:

      • Drag and drop the namespace into the System project or

      • Select ⋮ to the right of the namespace, click Move, then choose System from the Target Project dropdown

        Move to a New Project

    Configure rancher-monitoring to only watch for resources created by the Helm chart itself​

    Since each Project Monitoring Stack will watch the other namespaces and collect additional custom workload metrics or dashboards already, it's recommended to configure the following settings on all selectors to ensure that the Cluster Prometheus Stack only monitors resources created by the Helm Chart itself:

    matchLabels:
      release: "rancher-monitoring"

    The following selector fields are recommended to have this value:

    • .Values.alertmanager.alertmanagerSpec.alertmanagerConfigSelector
    • .Values.prometheus.prometheusSpec.serviceMonitorSelector
    • .Values.prometheus.prometheusSpec.podMonitorSelector
    • .Values.prometheus.prometheusSpec.ruleSelector
    • .Values.prometheus.prometheusSpec.probeSelector

    Once this setting is turned on, you can always create ServiceMonitors or PodMonitors that are picked up by the Cluster Prometheus by adding the label release: "rancher-monitoring" to them, in which case they will be ignored by Project Monitoring Stacks automatically by default, even if the namespace in which those ServiceMonitors or PodMonitors reside in are not system namespaces.

    note

    If you don't want to allow users to be able to create ServiceMonitors and PodMonitors that aggregate into the Cluster Prometheus in Project namespaces, you can additionally set the namespaceSelectors on the chart to only target system namespaces (which must contain cattle-monitoring-system and cattle-dashboards, where resources are deployed into by default by rancher-monitoring; you will also need to monitor the default namespace to get apiserver metrics or create a custom ServiceMonitor to scrape apiserver metrics from the Service residing in the default namespace) to limit your Cluster Prometheus from picking up other Prometheus Operator CRs. In that case, it would be recommended to turn .Values.prometheus.prometheusSpec.ignoreNamespaceSelectors=true to allow you to define ServiceMonitors that can monitor non-system namespaces from within a system namespace.

    Increase the CPU / memory limits of the Cluster Prometheus​

    Depending on a cluster's setup, it's generally recommended to give a large amount of dedicated memory to the Cluster Prometheus to avoid restarts due to out-of-memory errors (OOMKilled) usually caused by churn created in the cluster that causes a large number of high cardinality metrics to be generated and ingested by Prometheus within one block of time. This is one of the reasons why the default Rancher Monitoring stack expects around 4GB of RAM to be able to operate in a normal-sized cluster. However, when introducing Project Monitoring Stacks that are all sending /federate requests to the same Cluster Prometheus and are reliant on the Cluster Prometheus being "up" to federate that system data on their namespaces, it's even more important that the Cluster Prometheus has an ample amount of CPU / memory assigned to it to prevent an outage that can cause data gaps across all Project Prometheis in the cluster.

    note

    There are no specific recommendations on how much memory the Cluster Prometheus should be configured with since it depends entirely on the user's setup (namely the likelihood of encountering a high churn rate and the scale of metrics that could be generated at that time); it generally varies per setup.

    Install the Prometheus Federator Application​

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you want to install Prometheus Federator and click Explore.
    3. Click Apps -> Charts.
    4. Click the Prometheus Federator chart.
    5. Click Install.
    6. On the Metadata page, click Next.
    7. In the Project Release Namespace Project ID field, the System Project is used as the default but can be overridden with another project with similarly limited access. <!-- add info on retrieving project IDs >
    8. Click Install.

    Result: The Prometheus Federator app is deployed in the cattle-monitoring-system namespace.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.html index 88101459ba8..7ea843a3415 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/project-monitors.html @@ -5,13 +5,13 @@ Installing Project Monitors | Rancher Manager - +
    Version: v2.6

    Installing Project Monitors

    Install Project Monitors in each project where you want to enable project monitoring.

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to enable monitoring and click Explore.

    3. Click Monitoring > Project Monitors on the left nav bar. Then click Create in the upper right.

      Project Monitors

    4. Select your project from the drop-down menu, then click Create again.

      Create Project Monitors

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.html index 3b9b4e1ef4d..759f3da7344 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/set-up-workloads.html @@ -5,13 +5,13 @@ Setting up Prometheus Federator for a Workload | Rancher Manager - +
    Version: v2.6

    Setting up Prometheus Federator for a Workload

    Display CPU and Memory Metrics for a Workload​

    Displaying CPU and memory metrics with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer here.

    Setting up Metrics Beyond CPU and Memory​

    Setting up metrics beyond CPU and memory with Prometheus Federator is done the same way as with rancher-monitoring. For instructions, refer here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.html index 6280def0dba..293c095c1a8 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/prometheus-federator-guides/uninstall-prometheus-federator.html @@ -5,13 +5,13 @@ Uninstall Prometheus Federator | Rancher Manager - +
    Version: v2.6

    Uninstall Prometheus Federator

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Apps & Marketplace.
    4. Click Installed Apps.
    5. Go to the cattle-monitoring-system namespace and check the boxes for rancher-monitoring-crd and rancher-monitoring.
    6. Click Delete.
    7. Confirm Delete.

    Result: prometheus-federator is uninstalled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html index 6b0ba870f03..ed26f551000 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html @@ -5,13 +5,13 @@ Setting up Monitoring for a Workload | Rancher Manager - +
    Version: v2.6

    Setting up Monitoring for a Workload

    If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default.

    The steps for setting up monitoring for workloads depend on whether you want basic metrics such as CPU and memory for the workload, or whether you want to scrape custom metrics from the workload.

    If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default. The resource usage time series data is in Prometheus's local time series database.

    Grafana shows the data in aggregate, but you can see the data for the individual workload by using a PromQL query that extracts the data for that workload. Once you have the PromQL query, you can execute the query individually in the Prometheus UI and see the time series visualized there, or you can use the query to customize a Grafana dashboard to display the workload metrics. For examples of PromQL queries for workload metrics, see this section.

    To set up custom metrics for your workload, you will need to set up an exporter and create a new ServiceMonitor custom resource to configure Prometheus to scrape metrics from your exporter.

    Display CPU and Memory Metrics for a Workload​

    By default, the monitoring application already scrapes CPU and memory.

    To get some fine-grained detail for a particular workload, you can customize a Grafana dashboard to display the metrics for a particular workload.

    Setting up Metrics Beyond CPU and Memory​

    For custom metrics, you will need to expose the metrics on your application in a format supported by Prometheus.

    Then we recommend that you should create a new ServiceMonitor custom resource. When this resource is created, the Prometheus custom resource will be automatically updated so that its scrape configuration includes the new custom metrics endpoint. Then Prometheus will begin scraping metrics from the endpoint.

    You can also create a PodMonitor to expose the custom metrics endpoint, but ServiceMonitors are more appropriate for the majority of use cases.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html index 8d067e8bfd5..559250e9ee2 100644 --- a/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html +++ b/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html @@ -5,13 +5,13 @@ Uninstall Monitoring | Rancher Manager - +
    Version: v2.6

    Uninstall Monitoring

    1. Click ☰ > Cluster Management.
    2. Go to the cluster that you created and click Explore.
    3. In the left navigation bar, click Apps & Marketplace.
    4. Click Installed Apps.
    5. Go to the cattle-monitoring-system namespace and check the boxes for rancher-monitoring-crd and rancher-monitoring.
    6. Click Delete.
    7. Confirm Delete.

    Result: rancher-monitoring is uninstalled.

    Persistent Grafana Dashboards:

    For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation helm.sh/resource-policy: "keep". This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html index c0aab90f208..54e57b74b8c 100644 --- a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html +++ b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html @@ -5,13 +5,13 @@ Alertmanager Configuration | Rancher Manager - +
    Version: v2.6

    Alertmanager Configuration

    It is usually not necessary to directly edit the Alertmanager custom resource. For most use cases, you will only need to edit the Receivers and Routes to configure notifications.

    When Receivers and Routes are updated, the monitoring application will automatically update the Alertmanager custom resource to be consistent with those changes.

    note

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    About the Alertmanager Custom Resource​

    By default, Rancher Monitoring deploys a single Alertmanager onto a cluster that uses a default Alertmanager Config Secret.

    You may want to edit the Alertmanager custom resource if you would like to take advantage of advanced options that are not exposed in the Rancher UI forms, such as the ability to create a routing tree structure that is more than two levels deep.

    It is also possible to create more than one Alertmanager in a cluster, which may be useful if you want to implement namespace-scoped monitoring. In this case, you should manage the Alertmanager custom resources using the same underlying Alertmanager Config Secret.

    Deeply Nested Routes​

    While the Rancher UI only supports a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager YAML.

    Multiple Alertmanager Replicas​

    As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret.

    This Secret should be updated or modified any time you want to:

    • Add in new notifiers or receivers
    • Change the alerts that should be sent to specific notifiers or receivers
    • Change the group of alerts that are sent out

    By default, you can either choose to supply an existing Alertmanager Config Secret (i.e. any Secret in the cattle-monitoring-system namespace) or allow Rancher Monitoring to deploy a default Alertmanager Config Secret onto your cluster.

    By default, the Alertmanager Config Secret created by Rancher will never be modified or deleted on an upgrade or uninstall of the rancher-monitoring chart. This restriction prevents users from losing or overwriting their alerting configuration when executing operations on the chart.

    For more information on what fields can be specified in the Alertmanager Config Secret, please look at the Prometheus Alertmanager docs.

    The full spec for the Alertmanager configuration file and what it takes in can be found here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html index e8083fdde4f..8c4e2e46839 100644 --- a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html +++ b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html @@ -5,13 +5,13 @@ Prometheus Configuration | Rancher Manager - +
    Version: v2.6

    Prometheus Configuration

    It is usually not necessary to directly edit the Prometheus custom resource because the monitoring application automatically updates it based on changes to ServiceMonitors and PodMonitors.

    note

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    About the Prometheus Custom Resource

    The Prometheus CR defines a desired Prometheus deployment. The Prometheus Operator observes the Prometheus CR. When the CR changes, the Prometheus Operator creates prometheus-rancher-monitoring-prometheus, a Prometheus deployment based on the CR configuration.

    The Prometheus CR specifies details such as rules and what Alertmanagers are connected to Prometheus. Rancher builds this CR for you.

    Monitoring V2 only supports one Prometheus per cluster. However, you might want to edit the Prometheus CR if you want to limit monitoring to certain namespaces.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html index f4867506a09..cdd8f619ae8 100644 --- a/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html +++ b/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html @@ -5,13 +5,13 @@ Configuring PrometheusRules | Rancher Manager - +
    Version: v2.6

    Configuring PrometheusRules

    A PrometheusRule defines a group of Prometheus alerting and/or recording rules.

    note

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    Creating PrometheusRules in the Rancher UI​

    Prerequisite:

    The monitoring application needs to be installed.

    To create rule groups in the Rancher UI,

    1. Go to the cluster where you want to create rule groups. Click Monitoring > Advanced and click Prometheus Rules.
    2. Click Create.
    3. Enter a Group Name.
    4. Configure the rules. In Rancher's UI, we expect a rule group to contain either alert rules or recording rules, but not both. For help filling out the forms, refer to the configuration options below.
    5. Click Create.

    Result: Alerts can be configured to send notifications to the receiver(s).

    About the PrometheusRule Custom Resource​

    When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the spec of the Rule itself contains labels that are used by Alertmanager to figure out which Route should receive this Alert. For example, an Alert with the label team: front-end will be sent to all Routes that match on that label.

    Prometheus rule files are held in PrometheusRule custom resources. A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:

    • The name of the new alert or record
    • A PromQL expression for the new alert or record
    • Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
    • Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.

    For more information on what fields can be specified, please look at the Prometheus Operator spec.

    Use the label selector field ruleSelector in the Prometheus object to define the rule files that you want to be mounted into Prometheus.

    For examples, refer to the Prometheus documentation on recording rules and alerting rules.

    Configuration

    Rule Group​

    FieldDescription
    Group NameThe name of the group. Must be unique within a rules file.
    Override Group IntervalDuration in seconds for how often rules in the group are evaluated.

    Alerting Rules​

    Alerting rules allow you to define alert conditions based on PromQL (Prometheus Query Language) expressions and to send notifications about firing alerts to an external service.

    FieldDescription
    Alert NameThe name of the alert. Must be a valid label value.
    Wait To Fire ForDuration in seconds. Alerts are considered firing once they have been returned for this long. Alerts which have not yet fired for long enough are considered pending.
    PromQL ExpressionThe PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and all resultant time series will become pending/firing alerts. For more information, refer to the Prometheus documentation or our example PromQL expressions.
    LabelsLabels to add or overwrite for each alert.
    SeverityWhen enabled, labels are attached to the alert or record that identify it by the severity level.
    Severity Label ValueCritical, warning, or none
    AnnotationsAnnotations are a set of informational labels that can be used to store longer additional information, such as alert descriptions or runbook links. A runbook is a set of documentation about how to handle alerts. The annotation values can be templated.

    Recording Rules​

    Recording rules allow you to precompute frequently needed or computationally expensive PromQL (Prometheus Query Language) expressions and save their result as a new set of time series.

    FieldDescription
    Time Series NameThe name of the time series to output to. Must be a valid metric name.
    PromQL ExpressionThe PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and the result will be recorded as a new set of time series with the metric name as given by 'record'. For more information about expressions, refer to the Prometheus documentation or our example PromQL expressions.
    LabelsLabels to add or overwrite before storing the result.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html index 342140bf8f0..f7bd72731b0 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher Installed with Docker | Rancher Manager - +
    Version: v2.6

    Backing up Rancher Installed with Docker

    After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.

    Before You Start​

    During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  --volumes-from rancher-data-<DATE> -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

    In this command, <DATE> is a placeholder for the date that the data container and backup were created. 9-27-18 for example.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version of Rancher that you're creating a backup for.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped with docker ps -a. Use these commands for help anytime while creating backups.

    Creating a Backup​

    This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>
    3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
      docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
    4. From the data container that you just created (rancher-data-<DATE>), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). Use the following command, replacing each placeholder:
      docker run  --volumes-from rancher-data-<DATE> -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

      Step Result: A stream of commands runs on the screen.

    5. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    6. Move your backup tarball to a safe location external to your Rancher Server. Then delete the rancher-data-<DATE> container from your Rancher Server.

    7. Restart Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container:

      docker start <RANCHER_CONTAINER_NAME>

    Result: A backup tarball of your Rancher Server data is created. See Restoring Backups: Docker Installs if you need to restore backup data.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html index ccb21a53c33..817edf557e7 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html @@ -5,13 +5,13 @@ Backing up a Cluster | Rancher Manager - +
    Version: v2.6

    Backing up a Cluster

    In the Rancher UI, etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed.

    Rancher recommends configuring recurrent etcd snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.

    Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    How Snapshots Work

    Snapshot Components​

    When Rancher creates a snapshot, it includes three components:

    • The cluster data in etcd
    • The Kubernetes version
    • The cluster configuration in the form of the cluster.yml

    Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version.

    The multiple components of the snapshot allow you to select from the following options if you need to restore a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    It's always recommended to take a new snapshot before any upgrades.

    Generating the Snapshot from etcd Nodes​

    For each etcd node in the cluster, the etcd cluster health is checked. If the node reports that the etcd cluster is healthy, a snapshot is created from it and optionally uploaded to S3.

    The snapshot is stored in /opt/rke/etcd-snapshots. If the directory is configured on the nodes as a shared mount, it will be overwritten. On S3, the snapshot will always be from the last node that uploads it, as all etcd nodes upload it and the last will remain.

    In the case when multiple etcd nodes exist, any created snapshot is created after the cluster has been health checked, so it can be considered a valid snapshot of the data in the etcd cluster.

    Snapshot Naming Conventions​

    The name of the snapshot is auto-generated. The --name option can be used to override the name of the snapshot when creating one-time snapshots with the RKE CLI.

    When Rancher creates a snapshot of an RKE cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows:

    • m stands for manual
    • r stands for recurring
    • l stands for local
    • s stands for S3

    Some example snapshot names are:

    • c-9dmxz-rl-8b2cx
    • c-9dmxz-ml-kr56m
    • c-9dmxz-ms-t6bjb
    • c-9dmxz-rs-8gxc8

    How Restoring from a Snapshot Works​

    On restore, the following process is used:

    1. The snapshot is retrieved from S3, if S3 is configured.
    2. The snapshot is unzipped (if zipped).
    3. One of the etcd nodes in the cluster serves that snapshot file to the other nodes.
    4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore.
    5. The cluster is restored and post-restore actions will be done in the cluster.

    Configuring Recurring Snapshots

    Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.

    By default, Rancher launched Kubernetes clusters are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the S3 Target or replicating the path on disk is advised.

    During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for Cluster Options. Click on Show advanced options.

    In the Advanced Cluster Options section, there are several options available to configure:

    OptionDescriptionDefault Value
    etcd Snapshot Backup TargetSelect where you want the snapshots to be saved. Options are either local or in S3local
    Recurring etcd Snapshot EnabledEnable/Disable recurring snapshotsYes
    Recurring etcd Snapshot Creation PeriodTime in hours between recurring snapshots12 hours
    Recurring etcd Snapshot Retention CountNumber of snapshots to retain6

    One-Time Snapshots

    In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, navigate to the cluster where you want to take a one-time snapshot.
    3. Click ⋮ > Take Snapshot.

    Result: Based on your snapshot backup target, a one-time snapshot will be taken and saved in the selected backup target.

    Snapshot Backup Targets

    Rancher supports two different backup targets:

    Local Backup Target​

    By default, the local backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the Rancher launched Kubernetes clusters in /opt/rke/etcd-snapshots. All recurring snapshots are taken at configured intervals. The downside of using the local backup target is that if there is a total disaster and all etcd nodes are lost, there is no ability to restore the cluster.

    S3 Backup Target​

    The S3 backup target allows users to configure a S3 compatible backend to store the snapshots. The primary benefit of this option is that if the cluster loses all the etcd nodes, the cluster can still be restored as the snapshots are stored externally. Rancher recommends external targets like S3 backup, however its configuration requirements do require additional effort that should be considered.

    OptionDescriptionRequired
    S3 Bucket NameS3 bucket name where backups will be stored*
    S3 RegionS3 region for the backup bucket
    S3 Region EndpointS3 regions endpoint for the backup bucket*
    S3 Access KeyS3 access key with permission to access the backup bucket*
    S3 Secret KeyS3 secret key with permission to access the backup bucket*
    Custom CA CertificateA custom certificate used to access private S3 backends

    Using a custom CA certificate for S3​

    The backup snapshot can be stored on a custom S3 backup like minio. If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the Custom CA Certificate option to connect to the S3 backend.

    IAM Support for Storing Snapshots in S3​

    The S3 backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:

    • The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.

    • The cluster etcd nodes must have network access to the specified S3 endpoint.

    • The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket.

    • The Rancher Server worker node(s) must have network access to the specified S3 endpoint.

      To give an application access to S3, refer to the AWS documentation on Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.

    Viewing Available Snapshots

    The list of all available snapshots for the cluster is available in the Rancher UI.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the Clusters page, go to the cluster where you want to view the snapshots and click its name.
    3. Click the Snapshots tab to view the list of saved snapshots. These snapshots include a timestamp of when they were created.

    Safe Timestamps

    Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable.

    The option safe_timestamp is added to support compatible file names. When this flag is set to true, all special characters in the snapshot filename timestamp are replaced.

    This option is not available directly in the UI, and is only available through the Edit as Yaml interface.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html index 24e7e6372f9..c34f4c6d3e4 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher | Rancher Manager - +
    Version: v2.6

    Backing up Rancher

    In this section, you'll learn how to back up Rancher running on any Kubernetes cluster. To backup Rancher installed with Docker, refer the instructions for single node backups

    The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.

    Note that the rancher-backup operator version 2.x.x is for Rancher v2.6.x.

    caution

    When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different.

    Prerequisites​

    The Rancher version must be v2.5.0 and up.

    Refer here for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3.

    1. Install the Rancher Backups operator​

    The backup storage location is an operator-level setting, so it needs to be configured when the Rancher Backups application is installed or upgraded.

    Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, or they can be stored in a persistent volume.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the local cluster and click Explore. The local cluster runs the Rancher server.
    3. Click Apps & Marketplace > Charts.
    4. Click Rancher Backups.
    5. Click Install.
    6. Configure the default storage location. For help, refer to the storage configuration section.
    7. Click Install.
    note

    There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer here for a workaround.

    2. Perform a Backup​

    To perform a backup, a custom resource of type Backup must be created.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the local cluster and click Explore.

    3. In the left navigation bar, click Rancher Backups > Backups.

    4. Click Create.

    5. Create the Backup with the form, or with the YAML editor.

    6. For configuring the Backup details using the form, click Create and refer to the configuration reference and to the examples.

    7. For using the YAML editor, we can click Create > Create from YAML. Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3. The app uses the credentialSecretNamespace value to determine where to look for the S3 backup secret:

      apiVersion: resources.cattle.io/v1
      kind: Backup
      metadata:
        name: s3-recurring-backup
      spec:
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: rancher-backups
            folder: rancher
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com
        resourceSetName: rancher-resource-set
        encryptionConfigSecretName: encryptionconfig
        schedule: "@every 1h"
        retentionCount: 10
      note

      When creating the Backup resource using YAML editor, the resourceSetName must be set to rancher-resource-set

      For help configuring the Backup, refer to the configuration reference and to the examples.

      caution

      The rancher-backup operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup.

    8. Click Create.

    Result: The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html index aba4c77f2ff..380021b29f6 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html @@ -5,13 +5,13 @@ Migrating Rancher to a New Cluster | Rancher Manager - +
    Version: v2.6

    Migrating Rancher to a New Cluster

    If you are migrating Rancher to a new Kubernetes cluster, you don't need to install Rancher on the new cluster first. If Rancher is restored to a new cluster with Rancher already installed, it can cause problems.

    Prerequisites​

    These instructions assume you have created a backup and you have already installed a new Kubernetes cluster where Rancher will be deployed.

    caution

    It is required to use the same hostname that was set as the server URL in the first cluster. If not done, downstream clusters will show as unavailable in the cluster management page of the UI, and you won't be able to click inside the cluster or on the cluster's Explore button.

    Rancher version must be v2.5.0 and up

    Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes clusters such as Amazon EKS clusters. For help installing Kubernetes, refer to the documentation of the Kubernetes distribution. One of Rancher's Kubernetes distributions may also be used:

    1. Install the rancher-backup Helm chart​

    Install the rancher-backup chart, using a version in the 2.x.x major version range:

    1. Add the helm repository:

      helm repo add rancher-charts https://charts.rancher.io
      helm repo update

    2. Select and set CHART_VERSION variable with a 2.x.x rancher-backup release version:

      helm search repo --versions rancher-charts/rancher-backup
      CHART_VERSION=<2.x.x>

    3. Install the charts:

      helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION
      helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION
      note

      The above assumes an environment with outbound connectivity to Docker Hub

      For an air-gapped environment, use the Helm value below to pull the backup-restore-operator image from your private registry when installing the rancher-backup Helm chart.

      --set image.repository $REGISTRY/rancher/backup-restore-operator

    2. Restore from backup using a Restore custom resource​

    Important:

    Kubernetes v1.22, available as an experimental feature of v2.6.3, does not support restoring from backup files containing CRDs with the apiVersion apiextensions.k8s.io/v1beta1. In v1.22, the default resourceSet in the rancher-backup app is updated to collect only CRDs that use apiextensions.k8s.io/v1. There are currently two ways to work around this issue:

    1. Update the default resourceSet to collect the CRDs with the apiVersion v1.

    2. Update the default resourceSet and the client to use the new APIs internally, with apiextensions.k8s.io/v1 as the replacement.

      note

      When making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different.

    1. When using S3 object storage as the backup source for a restore that requires credentials, create a Secret object in this cluster to add the S3 credentials. The secret data must have two keys - accessKey, and secretKey, that contain the S3 credentials.

      The secret can be created in any namespace, this example uses the default namespace.

      kubectl create secret generic s3-creds \
        --from-literal=accessKey=<access key> \
        --from-literal=secretKey=<secret key>
      note

      Add your access key and secret key as values for accessKey and secretKey in the command above.

    2. Create a Restore object:

      During a migration, prune must be set to false. See the example below:

      # restore-migration.yaml
      apiVersion: resources.cattle.io/v1
      kind: Restore
      metadata:
        name: restore-migration
      spec:
        backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
        prune: false
        encryptionConfigSecretName: encryptionconfig
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: backup-test
            folder: ecm1
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com
      Important

      The field encryptionConfigSecretName should be used only if your backup was created with encryption enabled.

      If this applies, provide the name of the Secret object containing the encryption config file. If you only have the encryption config file, but don't have the secret created in this cluster, use the following steps to create the secret:

      1. Create an encryption configuration file

      2. The command below uses a file named encryption-provider-config.yaml, with the --from-file flag. Run the below once the EncryptionConfiguration is saved in a file called encryption-provider-config.yaml:

        kubectl create secret generic encryptionconfig \
          --from-file=./encryption-provider-config.yaml \
          -n cattle-resources-system

    3. Apply the manifest, and monitor the Restore status:

      1. Apply the Restore object resource:

        kubectl apply -f restore-migration.yaml

      2. Watch the Restore status:

        kubectl get restore

      3. Watch the restoration logs:

        kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup

      4. Once the Restore resource has the status Completed, you can continue the cert-manager and Rancher installation.

    3. Install cert-manager​

    Follow the steps to install cert-manager in the documentation about installing cert-manager on Kubernetes.

    4. Bring up Rancher with Helm​

    Use the same version of Helm to install Rancher, that was used on the first cluster.

    helm install rancher rancher-latest/rancher \
      --namespace cattle-system \
      --set hostname=<same hostname as the server URL from the first Rancher server> \
      --version x.y.z
    note

    If the original Rancher environment is running, you can collect the current values with a kubeconfig for the original environment:

    helm get values rancher -n cattle-system -o yaml > rancher-values.yaml

    These values can be reused using the rancher-values.yaml file. Be sure to switch the kubeconfig to the new Rancher environment.

    helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.yaml --version x.y.z
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html index 8d978c4a983..3294f17b2d2 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html @@ -5,13 +5,13 @@ Restoring Backups—Docker Installs | Rancher Manager - +
    Version: v2.6

    Restoring Backups—Docker Installs

    If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.

    Before You Start​

    During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
    busybox sh -c "rm /var/lib/rancher/* -rf  && \
    tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"

    In this command, <RANCHER_CONTAINER_NAME> and <RANCHER_VERSION>-<DATE> are environment variables for your Rancher deployment.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version number for your Rancher backup.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

    Restoring Backups​

    Using a backup that you created earlier, restore Rancher to its last known healthy state.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container:

      docker stop <RANCHER_CONTAINER_NAME>

    3. Move the backup tarball that you created during completion of Creating Backups—Docker Installs onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

      If you followed the naming convention we suggested in Creating Backups—Docker Installs, it will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    4. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes.

      danger

      This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.

      docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
      busybox sh -c "rm /var/lib/rancher/* -rf  && \
      tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

      Step Result: A series of commands should run.

    5. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data.

      docker start <RANCHER_CONTAINER_NAME>

    6. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html index 615b02818a0..053119e3b60 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html @@ -5,13 +5,13 @@ Restoring a Cluster from Backup | Rancher Manager - +
    Version: v2.6

    Restoring a Cluster from Backup

    etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed. Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    Rancher recommends enabling the ability to set up recurring snapshots of etcd, but one-time snapshots can easily be taken as well. Rancher allows restore from saved snapshots or if you don't have any snapshots, you can still restore etcd.

    Clusters can also be restored to a prior Kubernetes version and cluster configuration.

    Viewing Available Snapshots​

    The list of all available snapshots for the cluster is available.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the Clusters page, go to the cluster where you want to view the snapshots and click the name of the cluster.
    3. Click the Snapshots tab. The listed snapshots include a timestamp of when they were created.

    Restoring a Cluster from a Snapshot​

    If your Kubernetes cluster is broken, you can restore the cluster from a snapshot.

    Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the cluster.yml. These components allow you to select from the following options when restoring a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    When rolling back to a prior Kubernetes version, the upgrade strategy options are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state.

    Prerequisite:

    To restore snapshots from S3, the cluster needs to be configured to take recurring snapshots on S3.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. In the Clusters page, go to the cluster where you want to view the snapshots and click the name of the cluster.
    3. Click the Snapshots tab to view the list of saved snapshots.
    4. Go to the snapshot you want to restore and click ⋮ > Restore Snapshot.
    5. Click Restore.

    Result: The cluster will go into updating state and the process of restoring the etcd nodes from the snapshot will start. The cluster is restored when it returns to an active state.

    Recovering etcd without a Snapshot​

    If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. The cluster should have three etcd nodes to prevent a loss of quorum. If you want to recover your set of etcd nodes, follow these instructions:

    1. Keep only one etcd node in the cluster by removing all other etcd nodes.

    2. On the single remaining etcd node, run the following command:

      docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd

      This command outputs the running command for etcd, save this command to use later.

    3. Stop the running etcd container and rename it to etcd-old.

      docker stop etcd
      docker rename etcd etcd-old

    4. Take the saved command from Step 2 and revise it:

      • If you originally had more than 1 etcd node, then you need to change --initial-cluster to only contain the node that remains.
      • Add --force-new-cluster to the end of the command.

    5. Run the revised command.

    6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a custom cluster and you want to reuse an old node, you are required to clean up the nodes before attempting to add them back into a cluster.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html index 7eacc48974d..3d9a27eca32 100644 --- a/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html +++ b/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html @@ -5,13 +5,13 @@ Restoring Rancher | Rancher Manager - +
    Version: v2.6

    Restoring Rancher

    This page outlines how to perform a restore with Rancher.

    Important:
    • Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to migrate rancher.
    • While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore.
    • If you need to restore Rancher to a previous version after an upgrade, see the rollback documentation.

    Additional Steps for Rollbacks with Rancher v2.6.4+​

    In Rancher v2.6.4, the cluster-api module has been upgraded from v0.4.4 to v1.0.2 in which the apiVersion of CAPI CRDs are upgraded from cluster.x-k8s.io/v1alpha4 to cluster.x-k8s.io/v1beta1. This has the effect of causing rollbacks from Rancher v2.6.4 to any previous version of Rancher v2.6.x to fail because the previous version the CRDs needed to roll back are no longer available in v1beta1.

    To avoid this, the Rancher resource cleanup scripts should be run before the restore or rollback is attempted. Specifically, two scripts have been created to assist you: one to clean up the cluster (cleanup.sh), and one to check for any Rancher-related resources in the cluster (verify.sh). Details on the cleanup script can be found in the rancher/rancher-cleanup repo.

    caution

    Rancher will be down as the cleanup script runs as it deletes the resources created by rancher.

    The additional preparations:

    1. Follow these instructions to run the scripts.
    2. Follow these instructions to install the rancher-backup Helm chart on the existing cluster and restore the previous state.
      1. Omit Step 3.
      2. When Step 4 is reached, install the required Rancher v2.6.x version on the local cluster you intend to roll back to.

    Create the Restore Custom Resource​

    A restore is performed by creating a Restore custom resource.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the local cluster and click Explore. The local cluster runs the Rancher server.

    3. In the left navigation bar, click Rancher Backups > Restores.

    4. Click Create.

    5. Create the Restore with the form, or with YAML. For creating the Restore resource using form, refer to the configuration reference and to the examples.

    6. For using the YAML editor, we can click Create > Create from YAML. Enter the Restore YAML.

      apiVersion: resources.cattle.io/v1
      kind: Restore
      metadata:
        name: restore-migration
      spec:
        backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
        encryptionConfigSecretName: encryptionconfig
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: rancher-backups
            folder: rancher
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com

      For help configuring the Restore, refer to the configuration reference and to the examples.

    7. Click Create.

    Result: The rancher-operator scales down the rancher deployment during restore, and scales it back up once the restore completes. The resources are restored in this order:

    1. Custom Resource Definitions (CRDs)
    2. Cluster-scoped resources
    3. Namespaced resources

    Logs​

    To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:

    kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f

    Cleanup​

    If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores.

    Known Issues​

    In some cases, after restoring the backup, Rancher logs will show errors similar to the following:

    2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing

    This happens because one of the resources that was just restored has finalizers, but the related resources have been deleted so the handler cannot find it.

    To eliminate the errors, we need to find and delete the resource that causes the error. See more information here

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html b/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html index a469be3ac84..12ecf88a786 100644 --- a/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html +++ b/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html @@ -5,14 +5,14 @@ Fleet - GitOps at Scale | Rancher Manager - +
    Version: v2.6

    Fleet - GitOps at Scale

    Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It's also lightweight enough that it works great for a single cluster too, but it really shines when you get to a large scale. By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.

    Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.

    Architecture​

    For information about how Fleet works, see this page.

    Accessing Fleet in the Rancher UI​

    Fleet comes preinstalled in Rancher and is managed by the Continous Delivery option in the Rancher UI. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer here.

    Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following gitops practice.

    Follow the steps below to access Continuous Delivery in the Rancher UI:

    1. Click ☰ > Continuous Delivery.

    2. Select your namespace at the top of the menu, noting the following:

      • By default,fleet-default is selected which includes all downstream clusters that are registered through Rancher.
      • You may switch to fleet-local, which only contains the local cluster, or you may create your own workspace to which you may assign and move clusters.
      • You can then manage clusters by clicking on Clusters on the left navigation bar.

    3. Click on Gitrepos on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.

    4. Select your git repository and target clusters/cluster group. You can also create the cluster group in the UI by clicking on Cluster Groups from the left navigation bar.

    5. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.

    Windows Support​

    For details on support for clusters with Windows nodes, see this page.

    GitHub Repository​

    The Fleet Helm charts are available here.

    Using Fleet Behind a Proxy​

    For details on using Fleet behind a proxy, see this page.

    Helm Chart Dependencies​

    In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run helm install, your installation will fail because the dependencies will be missing.

    The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run helm dependencies update $chart OR run helm dependencies build $chart locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters.

    Troubleshooting​

    • Known Issue: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround:
      By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs here.

    Documentation​

    The Fleet documentation is at https://fleet.rancher.io/.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html b/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html index 4502b505a7f..1fd9fadf5c7 100644 --- a/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html +++ b/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html @@ -5,14 +5,14 @@ Multi-cluster Apps | Rancher Manager - +
    Version: v2.6

    Multi-cluster Apps

    As of Rancher v2.5, multi-cluster apps are deprecated. We now recommend using Fleet for deploying apps across clusters.

    Typically, most applications are deployed on a single Kubernetes cluster, but there will be times you might want to deploy multiple copies of the same application across different clusters and/or projects. In Rancher, a multi-cluster application, is an application deployed using a Helm chart across multiple clusters. With the ability to deploy the same application across multiple clusters, it avoids the repetition of the same action on each cluster, which could introduce user error during application configuration. With multi-cluster applications, you can customize to have the same configuration across all projects/clusters as well as have the ability to change the configuration based on your target project. Since multi-cluster application is considered a single application, it's easy to manage and maintain this application.

    Any Helm charts from a global catalog can be used to deploy and manage multi-cluster applications.

    After creating a multi-cluster application, you can program a global DNS entry to make it easier to access the application.

    Prerequisites​

    Permissions​

    To create a multi-cluster app in Rancher, you must have at least one of the following permissions:

    • A project-member role in the target cluster(s), which gives you the ability to create, read, update, and delete the workloads
    • A cluster owner role for the clusters(s) that include the target project(s)

    Enable Legacy Features​

    Because multi-cluster apps were deprecated and replaced with Fleet in Rancher v2.5, you will need to enable multi-cluster apps with a feature flag.

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags.
    3. Go to the legacy feature flag and click Activate.

    Launching a Multi-Cluster App​

    1. In the upper left corner, click ☰ > Multi-cluster Apps.
    2. Click Launch.
    3. Find the application that you want to launch.
    4. (Optional) Review the detailed descriptions, which are derived from the Helm chart's README.
    5. Under Configuration Options enter a Name for the multi-cluster application. By default, this name is also used to create a Kubernetes namespace in each target project for the multi-cluster application. The namespace is named as <MULTI-CLUSTER_APPLICATION_NAME>-<PROJECT_ID>.
    6. Select a Template Version.
    7. Complete the multi-cluster applications specific configuration options as well as the application configuration options.
    8. Select the Members who can interact with the multi-cluster application.
    9. Add any custom application configuration answers that would change the configuration for specific project(s) from the default application configuration answers.
    10. Review the files in the Preview section. When you're satisfied, click Launch.

    Result: Your application is deployed to your chosen namespace. You can view the application status from the project's:

    Multi-cluster App Configuration Options​

    Rancher has divided the configuration option for the multi-cluster application into several sections.

    Targets​

    In the Targets section, select the projects that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on -.

    Upgrades​

    In the Upgrades section, select the upgrade strategy to use, when you decide to upgrade your application.

    • Rolling Update (batched): When selecting this upgrade strategy, the number of applications upgraded at a time is based on the selected Batch size and the Interval specifies how many seconds to wait before starting the next batch of updates.

    • Upgrade all apps simultaneously: When selecting this upgrade strategy, all applications across all projects will be upgraded at the same time.

    Roles​

    In the Roles section, you define the role of the multi-cluster application. Typically, when a user launches catalog applications, that specific user's permissions are used for creation of all workloads/resources that is required by the app.

    For multi-cluster applications, the application is deployed by a system user and is assigned as the creator of all underlying resources. A system user is used instead of the actual user due to the fact that the actual user could be removed from one of the target projects. If the actual user was removed from one of the projects, then that user would no longer be able to manage the application for the other projects.

    Rancher will let you select from two options for Roles, Project and Cluster. Rancher will allow creation using any of these roles based on the user's permissions.

    • Project - This is the equivalent of a project member. If you select this role, Rancher will check that in all the target projects, the user has minimally the project member role. While the user might not be explicitly granted the project member role, if the user is an administrator, a cluster owner, or a project owner, then the user is considered to have the appropriate level of permissions.

    • Cluster - This is the equivalent of a cluster owner. If you select this role, Rancher will check that in all the target projects, the user has minimally the cluster owner role. While the user might not be explicitly granted the cluster owner role, if the user is an administrator, then the user is considered to have the appropriate level of permissions.

    When launching the application, Rancher will confirm if you have these permissions in the target projects before launching the application.

    note

    There are some applications like Grafana or Datadog that require access to specific cluster-scoped resources. These applications will require the Cluster role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles.

    Application Configuration Options​

    For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in Using Helm: The format and limitations of –set, as Rancher passes them as --set flags to Helm.

    Example

    When entering an answer that includes two values separated by a comma (i.e. abc, bcd), it is required to wrap the values with double quotes (i.e., "abc, bcd").

    Using a questions.yml file​

    If the Helm chart that you are deploying contains a questions.yml file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.

    Key Value Pairs for Native Helm Charts​

    For native Helm charts (i.e., charts from the Helm Stable or Helm Incubator catalogs or a custom Helm chart repository, answers are provided as key value pairs in the Answers section. These answers are used to override the default values.

    Members​

    By default, multi-cluster applications can only be managed by the user who created it. In the Members section, other users can be added so that they can also help manage or view the multi-cluster application.

    1. Find the user that you want to add by typing in the member's name in the Member search box.

    2. Select the Access Type for that member. There are three access types for a multi-cluster project, but due to how the permissions of a multi-cluster application are launched, please read carefully to understand what these access types mean.

      • Owner: This access type can manage any configuration part of the multi-cluster application including the template version, the [multi-cluster applications specific configuration options](#Multi-cluster App Configuration Options), the application specific configuration options, the members who can interact with the multi-cluster application and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any owner of the multi-cluster application can manage/remove applications in target projects without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Member: This access type can only modify the template version, the application specific configuration options and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any member of the multi-cluster application can modify the application without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Read-only: This access type cannot modify any configuration option for the multi-cluster application. Users can only view these applications.

      caution

      Please ensure only trusted users are given Owner or Member access as they will automatically be able to manage applications created for this multi-cluster application in target projects they might not have direct access to.

    Overriding Application Configuration Options for Specific Projects​

    The ability to use the same configuration to deploy the same application across multiple clusters/projects is one of the main benefits of multi-cluster applications. There might be a specific project that requires a slightly different configuration option, but you want to manage that application with all the other matching applications. Instead of creating a brand new application, you can override specific application specific configuration options for specific projects.

    1. In the Answer Overrides section, click Add Override.

    2. For each override, you can select the following:

      • Scope: Select which target projects you want to override the answer in the configuration option.

      • Question: Select which question you want to override.

      • Answer: Enter the answer that you want to be used instead.

    Upgrading Multi-Cluster App Roles and Projects​

    • Changing Roles on an existing Multi-Cluster app The creator and any users added with the access-type "owner" to a multi-cluster app, can upgrade its Roles. When adding a new Role, we check if the user has that exact role in all current target projects. These checks allow the same relaxations for global admins, cluster owners and project-owners as described in the installation section for the field Roles.

    • Adding/Removing target projects

    1. The creator and any users added with access-type "owner" to a multi-cluster app, can add or remove its target projects. When adding a new project, we check if the caller of this request has all Roles defined on multi-cluster app, in the new projects they want to add. The roles checks are again relaxed for global admins, cluster-owners and project-owners.
    2. We do not do these membership checks when removing target projects. This is because the caller's permissions could have with respect to the target project, or the project could have been deleted and hence the caller wants to remove it from targets list.

    Multi-Cluster Application Management​

    One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back.

    Prerequisite:

    The legacy feature flag needs to be enabled.

    1. In the upper left corner, click ☰ > Multi-cluster Apps.

    2. Choose the multi-cluster application you want to take one of these actions on and click the ⋮. Select one of the following options:

      • Clone: Creates another multi-cluster application with the same configuration. By using this option, you can easily duplicate a multi-cluster application.
      • Upgrade: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the upgrade strategy can be modified if you have the correct access type.
      • Rollback: Rollback your application to a specific version. If after an upgrade, there are issues for your multi-cluster application for one or more of your targets, Rancher has stored up to 10 versions of the multi-cluster application. Rolling back a multi-cluster application reverts the application for all target clusters and projects, not just the targets(s) affected by the upgrade issue.

    Deleting a Multi-Cluster Application​

    Prerequisite:

    The legacy feature flag needs to be enabled.

    1. In the upper left corner, click ☰ > Multi-cluster Apps.

    2. Choose the multi-cluster application you want to delete and click the ⋮ > Delete. When deleting the multi-cluster application, all applications and namespaces are deleted in all of the target projects.

      note

      The applications in the target projects, that are created for a multi-cluster application, cannot be deleted individually. The applications can only be deleted when the multi-cluster application is deleted.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.html b/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.html index dc8d29308bb..843dc76724f 100644 --- a/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.html +++ b/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps.html @@ -5,13 +5,13 @@ Creating Apps | Rancher Manager - +
    Version: v2.6

    Creating Apps

    Rancher's App Marketplace is based on Helm Repositories and Helm Charts. You can add HTTP based standard Helm Repositories as well as any Git Repository which contains charts.

    tip

    For a complete walkthrough of developing charts, see the Chart Template Developer's Guide in the official Helm documentation.

    Chart Types

    Rancher supports two different types of charts: Helm charts and Rancher charts.

    Helm Charts​

    Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you' can provide the chart's parameter values in a YAML editor.

    Rancher Charts​

    Rancher charts are native helm charts with two files that enhance user experience: app-readme.md and questions.yaml. Read more about them in Additional Files for Rancher Charts.

    Rancher charts add simplified chart descriptions and configuration forms to make the application deployment easy. Rancher users do not need to read through the entire list of Helm variables to understand how to launch an application.

    Chart Directory Structure

    You can provide Helm Charts in a standard, HTTP based Helm Repository. For more information see the Chart Repository Guide in the official Helm documentation.

    Alternatively you can organize your charts in a Git Repository and directly add this to the App Marketplace.

    The following table demonstrates the directory structure for a Git repository. The charts directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. The questions.yaml, README.md, and requirements.yml files are specific to Rancher charts, but are optional for chart customization.

    <Repository-Base>/
     │
     ├── charts/
     │   ├── <Application Name>/      # This directory name will be surfaced in the Rancher UI as the chart name
     │   │   ├── <App Version>/   # Each directory at this level provides different app versions that will be selectable within the chart in the Rancher UI
     │   │   │   ├── Chart.yaml   # Required Helm chart information file.
     │   │   │   ├── questions.yaml   # Form questions displayed within the Rancher UI. Questions display in Configuration Options.*
     │   │   │   ├── README.md         # Optional: Helm Readme file displayed within Rancher UI. This text displays in Detailed Descriptions.
     │   │   │   ├── requirements.yml  # Optional: YAML file listing dependencies for the chart.
     │   │   │   ├── values.yml        # Default configuration values for the chart.
     │   │   │   ├── templates/        # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML.

    Additional Files for Rancher Charts

    Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not.

    • app-readme.md

      A file that provides descriptive text in the chart's UI header.

    • questions.yml

      A file that contains questions for a form. These form questions simplify deployment of a chart. Without it, you must configure the deployment using a values YAML config, which is more difficult. The following image displays the difference between a Rancher chart (which includes questions.yml) and a native Helm chart (which does not).

    <figcaption>Rancher Chart with <code>questions.yml</code> (top) vs. Helm Chart without (bottom)</figcaption>

    ![questions.yml](/img/rancher-app-2.6.png)
    ![values.yaml](/img/helm-app-2.6.png)

    Chart.yaml annotations​

    Rancher supports additional annotations that you can add to the Chart.yaml file. These annotations allow you to define application dependencies or configure additional UI defaults:

    AnnotationDescriptionExample
    catalog.cattle.io/auto-installIf set, will install the specified chart in the specified version before installing this chartother-chart-name=1.0.0
    catalog.cattle.io/display-nameA display name that should be displayed in the App Marketplace instead of the chart nameDisplay Name of Chart
    catalog.cattle.io/namespaceA fixed namespace where the chart should be deployed in. If set, this can't be changed by the userfixed-namespace
    catalog.cattle.io/release-nameA fixed release name for the Helm installation. If set, this can't be changed by the userfixed-release-name
    catalog.cattle.io/requests-cpuTotal amount of CPU that should be unreserverd in the cluster. If less CPU is available, a warning will be shown2000m
    catalog.cattle.io/requests-memoryTotal amount of memory that should be unreserverd in the cluster. If less memory is available, a warning will be shown2Gi
    catalog.cattle.io/osRestricts the OS where this chart can be installed. Possible values: linux, windows. Default: no restrictionlinux

    questions.yml​

    Inside the questions.yml, most of the content will be around the questions to ask the end user, but there are some additional fields that can be set in this file.

    Min/Max Rancher versions​

    For each chart, you can add the minimum and/or maximum Rancher version, which determines whether or not this chart is available to be deployed from Rancher.

    note

    Even though Rancher release versions are prefixed with a v, there is no prefix for the release version when using this option.

    rancher_min_version: 2.3.0
    rancher_max_version: 2.3.99

    Question Variable Reference​

    This reference contains variables that you can use in questions.yml nested under questions:.

    VariableTypeRequiredDescription
    variablestringtrueDefine the variable name specified in the values.yml file, using foo.bar for nested objects.
    labelstringtrueDefine the UI label.
    descriptionstringfalseSpecify the description of the variable.
    typestringfalseDefault to string if not specified (current supported types are string, multiline, boolean, int, enum, password, storageclass, hostname, pvc, and secret).
    requiredboolfalseDefine if the variable is required or not (true | false)
    defaultstringfalseSpecify the default value. Only used if there is no corresponding value in the values.yml file.
    groupstringfalseGroup questions by input value.
    min_lengthintfalseMin character length.
    max_lengthintfalseMax character length.
    minintfalseMin integer length.
    maxintfalseMax integer length.
    options[]stringfalseSpecify the options when the variable type is enum, for example: options:
    - "ClusterIP"
    - "NodePort"
    - "LoadBalancer"
    valid_charsstringfalseRegular expression for input chars validation.
    invalid_charsstringfalseRegular expression for invalid input chars validation.
    subquestions[]subquestionfalseAdd an array of subquestions.
    show_ifstringfalseShow current variable if conditional variable is true. For example show_if: "serviceType=Nodeport"
    show_subquestion_ifstringfalseShow subquestions if is true or equal to one of the options. for example show_subquestion_if: "true"
    note

    subquestions[] cannot contain subquestions or show_subquestions_if keys, but all other keys in the above table are supported.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html b/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html index 58f05caf41e..1e55a600bb6 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html @@ -5,13 +5,13 @@ Setting up Amazon ELB Network Load Balancer | Rancher Manager - +
    Version: v2.6

    Setting up Amazon ELB Network Load Balancer

    This how-to guide describes how to set up a Network Load Balancer (NLB) in Amazon's EC2 service that will direct traffic to multiple instances on EC2.

    These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required.

    This tutorial is about one possible way to set up your load balancer, not the only way. Other types of load balancers, such as a Classic Load Balancer or Application Load Balancer, could also direct traffic to the Rancher server nodes.

    Rancher only supports using the Amazon NLB when terminating traffic in tcp mode for port 443 rather than tls mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB.

    Requirements​

    These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes.

    1. Create Target Groups​

    Begin by creating two target groups for the TCP protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups.

    Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but it's convenient to add a listener for port 80, because traffic to port 80 will be automatically redirected to port 443.

    Regardless of whether an NGINX Ingress or Traefik Ingress controller is used, the Ingress should redirect traffic from port 80 to port 443.

    1. Log into the Amazon AWS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. Select Services and choose EC2, find the section Load Balancing and open Target Groups.
    3. Click Create target group to create the first target group, regarding TCP port 443.
    note

    Health checks are handled differently based on the Ingress. For details, refer to this section.

    Target Group (TCP port 443)​

    Configure the first target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-443
    Target typeinstance
    ProtocolTCP
    Port443
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Portoverride,80
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    Click Create target group to create the second target group, regarding TCP port 80.

    Target Group (TCP port 80)​

    Configure the second target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-80
    Target typeinstance
    ProtocolTCP
    Port80
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Porttraffic port
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    2. Register Targets​

    Next, add your Linux nodes to both target groups.

    Select the target group named rancher-tcp-443, click the tab Targets and choose Edit.

    Select the instances (Linux nodes) you want to add, and click Add to registered.

    Screenshot Add targets to target group TCP port 443

    Screenshot Added targets to target group TCP port 443

    When the instances are added, click Save on the bottom right of the screen.

    Repeat those steps, replacing rancher-tcp-443 with rancher-tcp-80. The same instances need to be added as targets to this target group.

    3. Create Your NLB​

    Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in 1. Create Target Groups.

    1. From your web browser, navigate to the Amazon EC2 Console.

    2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

    3. Click Create Load Balancer.

    4. Choose Network Load Balancer and click Create. Then complete each form.

    Step 1: Configure Load Balancer​

    Set the following fields in the form:

    • Name: rancher
    • Scheme: internal or internet-facing. The scheme that you choose for your NLB is dependent on the configuration of your instances and VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to internal rather than internet-facing.
    • Listeners: The Load Balancer Protocol should be TCP and the corresponding Load Balancer Port should be set to 443.
    • Availability Zones: Select Your VPC and Availability Zones.

    Step 2: Configure Routing​

    1. From the Target Group drop-down, choose Existing target group.
    2. From the Name drop-down, choose rancher-tcp-443.
    3. Open Advanced health check settings, and configure Interval to 10 seconds.

    Step 3: Register Targets​

    Since you registered your targets earlier, all you have to do is click Next: Review.

    Step 4: Review​

    Look over the load balancer details and click Create when you're satisfied.

    After AWS creates the NLB, click Close.

    4. Add listener to NLB for TCP port 80

    1. Select your newly created NLB and select the Listeners tab.

    2. Click Add listener.

    3. Use TCP:80 as Protocol : Port

    4. Click Add action and choose Forward to...

    5. From the Forward to drop-down, choose rancher-tcp-80.

    6. Click Save in the top right of the screen.

    Health Check Paths for NGINX Ingress and Traefik Ingresses

    K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default.

    For RKE Kubernetes clusters, NGINX Ingress is used by default, whereas for K3s Kubernetes clusters, Traefik is the default Ingress.

    • Traefik: The health check path is /ping. By default /ping is always matched (regardless of Host), and a response from Traefik itself is always served.
    • NGINX Ingress: The default backend of the NGINX Ingress controller has a /healthz endpoint. By default /healthz is always matched (regardless of Host), and a response from ingress-nginx itself is always served.

    To simulate an accurate health check, it is a best practice to use the Host header (Rancher hostname) combined with /ping or /healthz (for K3s or for RKE clusters, respectively) wherever possible, to get a response from the Rancher Pods, not the Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html b/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html index 30ad99c36be..69739567b23 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html @@ -5,13 +5,13 @@ Set up Infrastructure for a High Availability K3s Kubernetes Cluster | Rancher Manager - +
    Version: v2.6

    Set up Infrastructure for a High Availability K3s Kubernetes Cluster

    This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.

    The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.

    For more information about each installation option, refer to this page.

    Important:

    These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure:

    • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • An external database to store the cluster data. We recommend MySQL.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up External Datastore​

    The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

    For a high-availability K3s installation, you will need to set a MySQL external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore.

    When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database.

    For an example of one way to set up the MySQL database, refer to this tutorial for setting up MySQL on Amazon's RDS service.

    For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

    3. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    caution

    Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html b/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html index 6a84623d081..bea02c8602e 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html @@ -5,13 +5,13 @@ Set up Infrastructure for a High Availability RKE Kubernetes Cluster | Rancher Manager - +
    Version: v2.6

    Set up Infrastructure for a High Availability RKE Kubernetes Cluster

    This tutorial is intended to help you create a high-availability RKE cluster that can be used to install a Rancher server.

    Important:

    These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
    • A load balancer to direct front-end traffic to the three nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    These nodes must be in the same region/data center. You may place these servers in separate availability zones.

    Why three nodes?​

    In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

    The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on any of the three nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    caution

    Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    3. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html b/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html index d3b8590558b..3f3a1db99d1 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html @@ -5,13 +5,13 @@ Set up Infrastructure for a High Availability RKE2 Kubernetes Cluster | Rancher Manager - +
    Version: v2.6

    Set up Infrastructure for a High Availability RKE2 Kubernetes Cluster

    This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.

    The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a RKE2 Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.

    Important:

    These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability RKE2 cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on all nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE2 tool will deploy an Nginx Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Nginx Ingress controller to listen for traffic destined for the Rancher hostname. The Nginx Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    caution

    Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html b/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html index 58338bbf745..0b97679cb57 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html @@ -5,13 +5,13 @@ Setting up a MySQL Database in Amazon RDS | Rancher Manager - +
    Version: v2.6

    Setting up a MySQL Database in Amazon RDS

    This tutorial describes how to set up a MySQL database in Amazon's RDS.

    This database can later be used as an external datastore for a high-availability K3s Kubernetes cluster.

    1. Log into the Amazon AWS RDS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. In the left panel, click Databases.
    3. Click Create database.
    4. In the Engine type section, click MySQL.
    5. In the Version section, choose MySQL 5.7.22.
    6. In Settings section, under Credentials Settings, enter a master password for the admin master username. Confirm the password.
    7. Expand the Additional configuration section. In the Initial database name field, enter a name. The name can have only letters, numbers, and underscores. This name will be used to connect to the database.
    8. Click Create database.

    You'll need to capture the following information about the new database so that the K3s Kubernetes cluster can connect to it.

    To see this information in the Amazon RDS console, click Databases, and click the name of the database that you created.

    • Username: Use the admin username.
    • Password: Use the admin password.
    • Hostname: Use the Endpoint as the hostname. The endpoint is available in the Connectivity & security section.
    • Port: The port should be 3306 by default. You can confirm it in the Connectivity & security section.
    • Database name: Confirm the name by going to the Configuration tab. The name is listed under DB name.

    This information will be used to connect to the database in the following format:

    mysql://username:password@tcp(hostname:3306)/database-name

    For more information on configuring the datastore for K3s, refer to the K3s documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html b/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html index d5609a1c260..3a126a4f38a 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html @@ -5,13 +5,13 @@ Setting up an NGINX Load Balancer | Rancher Manager - +
    Version: v2.6

    Setting up an NGINX Load Balancer

    NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes.

    In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX.

    note

    Do not use one of your Rancher nodes as the load balancer.

    These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required.

    Install NGINX​

    Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are 1.14 and 1.15. For help installing NGINX, refer to their install documentation.

    The stream module is required, which is present when using the official NGINX packages. Please refer to your OS documentation on how to install and enable the NGINX stream module on your operating system.

    Create NGINX Configuration​

    After installing NGINX, you need to update the NGINX configuration file, nginx.conf, with the IP addresses for your nodes.

    1. Copy and paste the code sample below into your favorite text editor. Save it as nginx.conf.

    2. From nginx.conf, replace both occurrences (port 80 and port 443) of <IP_NODE_1>, <IP_NODE_2>, and <IP_NODE_3> with the IPs of your nodes.

      note

      See NGINX Documentation: TCP and UDP Load Balancing for all configuration options.

      Example NGINX config
      worker_processes 4;
      worker_rlimit_nofile 40000;

      events {
          worker_connections 8192;
      }

      stream {
          upstream rancher_servers_http {
              least_conn;
              server <IP_NODE_1>:80 max_fails=3 fail_timeout=5s;
              server <IP_NODE_2>:80 max_fails=3 fail_timeout=5s;
              server <IP_NODE_3>:80 max_fails=3 fail_timeout=5s;
          }
          server {
              listen 80;
              proxy_pass rancher_servers_http;
          }

          upstream rancher_servers_https {
              least_conn;
              server <IP_NODE_1>:443 max_fails=3 fail_timeout=5s;
              server <IP_NODE_2>:443 max_fails=3 fail_timeout=5s;
              server <IP_NODE_3>:443 max_fails=3 fail_timeout=5s;
          }
          server {
              listen     443;
              proxy_pass rancher_servers_https;
          }

      }

    1. Save nginx.conf to your load balancer at the following path: /etc/nginx/nginx.conf.

    2. Load the updates to your NGINX configuration by running the following command:

      # nginx -s reload

    Option - Run NGINX as Docker container​

    Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited Example NGINX config as /etc/nginx.conf and run the following command to launch the NGINX container:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /etc/nginx.conf:/etc/nginx/nginx.conf \
      nginx:1.14
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html b/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html index d0c73187992..ac1b857acd0 100644 --- a/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html +++ b/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html @@ -5,13 +5,13 @@ Setting up Nodes in Amazon EC2 | Rancher Manager - +
    Version: v2.6

    Setting up Nodes in Amazon EC2

    In this tutorial, you will learn one way to set up Linux nodes for the Rancher management server. These nodes will fulfill the node requirements for OS, Docker, hardware, and networking.

    If the Rancher server will be installed on an RKE Kubernetes cluster, you should provision three instances.

    If the Rancher server will be installed on a K3s Kubernetes cluster, you only need to provision two instances.

    If the Rancher server is installed in a single Docker container, you only need one instance.

    1. Optional Preparation​

    • Create IAM role: To allow Rancher to manipulate AWS resources, such as provisioning new storage or new nodes, you will need to configure Amazon as a cloud provider. There are several things you'll need to do to set up the cloud provider on EC2, but part of this process is setting up an IAM role for the Rancher server nodes. For the full details on setting up the cloud provider, refer to this page.
    • Create security group: We also recommend setting up a security group for the Rancher nodes that complies with the port requirements for Rancher nodes.

    2. Provision Instances​

    1. Log into the Amazon AWS EC2 Console to get started. Make sure to take note of the Region where your EC2 instances (Linux nodes) are created, because all of the infrastructure for the Rancher management server should be in the same region.
    2. In the left panel, click Instances.
    3. Click Launch Instance.
    4. In the section called Step 1: Choose an Amazon Machine Image (AMI), we will use Ubuntu 18.04 as the Linux OS, using ami-0d1cd67c26f5fca19 (64-bit x86). Go to the Ubuntu AMI and click Select.
    5. In the Step 2: Choose an Instance Type section, select the t2.medium type.
    6. Click Next: Configure Instance Details.
    7. In the Number of instances field, enter the number of instances. A high-availability K3s cluster requires only two instances, while a high-availability RKE cluster requires three instances.
    8. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the IAM role field.
    9. Click Next: Add Storage, Next: Add Tags, and Next: Configure Security Group.
    10. In Step 6: Configure Security Group, select a security group that complies with the port requirements for Rancher nodes.
    11. Click Review and Launch.
    12. Click Launch.
    13. Choose a new or existing key pair that you will use to connect to your instance later. If you are using an existing key pair, make sure you already have access to the private key.
    14. Click Launch Instances.

    Result: You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking.

    note

    If the nodes are being used for an RKE Kubernetes cluster, install Docker on each node in the next step. For a K3s Kubernetes cluster, the nodes are now ready to install K3s.

    3. Install Docker and Create User for RKE Kubernetes Cluster Nodes​

    1. From the AWS EC2 console, click Instances in the left panel.
    2. Go to the instance that you want to install Docker on. Select the instance and click Actions > Connect.
    3. Connect to the instance by following the instructions on the screen that appears. Copy the Public DNS of the instance. An example command to SSH into the instance is as follows:
    sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance]
    1. Run the following command on the instance to install Docker with one of Rancher's installation scripts:
    curl https://releases.rancher.com/install-docker/18.09.sh | sh
    1. When you are connected to the instance, run the following command on the instance to create a user:
    sudo usermod -aG docker ubuntu
    1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server.
    tip

    To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher’s Docker installation scripts.

    Result: You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking.

    Next Steps for RKE Kubernetes Cluster Nodes​

    If you are going to install an RKE cluster on the new nodes, take note of the IPv4 Public IP and Private IP of each node. This information can be found on the Description tab for each node after it is created. The public and private IP will be used to populate the address and internal_address of each node in the RKE cluster configuration file, rancher-cluster.yml.

    RKE will also need access to the private key to connect to each node. Therefore, you might want to take note of the path to your private keys to connect to the nodes, which can also be included in the rancher-cluster.yml under the ssh_key_path directive for each node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html b/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html index 51c51b59df6..39da1883993 100644 --- a/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html +++ b/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html @@ -5,13 +5,13 @@ About High-availability Installations | Rancher Manager - +
    Version: v2.6

    About High-availability Installations

    We recommend using Helm, a Kubernetes package manager, to install Rancher on a dedicated Kubernetes cluster. This is called a high-availability Kubernetes installation because increased availability is achieved by running Rancher on multiple nodes.

    In a standard installation, Kubernetes is first installed on three nodes that are hosted in an infrastructure provider such as Amazon's EC2 or Google Compute Engine.

    Then Helm is used to install Rancher on top of the Kubernetes cluster. Helm uses Rancher's Helm chart to install a replica of Rancher on each of the three nodes in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster, in order to increase Rancher's availability.

    The Rancher server data is stored on etcd. This etcd database also runs on all three nodes, and requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup.

    For information on how Rancher works, regardless of the installation method, refer to the architecture section.

    • DNS for Rancher should resolve to a layer 4 load balancer
    • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
    • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
    • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
    Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers

    High-availability Kubernetes Installation of Rancher

    Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html b/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html index c189dcd4983..09b78aace02 100644 --- a/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html +++ b/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html @@ -5,13 +5,13 @@ Setting up a High-availability K3s Kubernetes Cluster for Rancher | Rancher Manager - +
    Version: v2.6

    Setting up a High-availability K3s Kubernetes Cluster for Rancher

    This section describes how to install a Kubernetes cluster according to the best practices for the Rancher server environment.

    For systems without direct internet access, refer to the air gap installation instructions.

    Single-node Installation Tip:

    In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Prerequisites

    These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in this section.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

    Installing Kubernetes

    1. Install Kubernetes and Set up the K3s Server​

    When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier.

    1. Connect to one of the Linux nodes that you have prepared to run the Rancher server.

    2. On the Linux node, run this command to start the K3s server and connect it to the external datastore:

      curl -sfL https://get.k3s.io | sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"

      To specify the K3s version, use the INSTALL_K3S_VERSION environment variable:

      curl -sfL https://get.k3s.io |  INSTALL_K3S_VERSION=vX.Y.Z sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"
      note

      The datastore endpoint can also be passed in using the environment variable $K3S_DATASTORE_ENDPOINT.

    3. Repeat the same command on your second K3s server node.

    2. Confirm that K3s is Running​

    To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes:

    sudo k3s kubectl get nodes

    Then you should see two nodes with the master role:

    ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes
    NAME               STATUS   ROLES    AGE    VERSION
    ip-172-31-60-194   Ready    master   44m    v1.17.2+k3s1
    ip-172-31-63-88    Ready    master   6m8s   v1.17.2+k3s1

    Then test the health of the cluster pods:

    sudo k3s kubectl get pods --all-namespaces

    Result: You have successfully set up a K3s Kubernetes cluster.

    3. Save and Start Using the kubeconfig File​

    When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    4. Check the Health of Your Cluster Pods​

    Now that you have set up the kubeconfig file, you can use kubectl to access the cluster from your local machine.

    Check that all the required pods and containers are healthy are ready to continue:

    ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces
    NAMESPACE       NAME                                      READY   STATUS    RESTARTS   AGE
    kube-system     metrics-server-6d684c7b5-bw59k            1/1     Running   0          8d
    kube-system     local-path-provisioner-58fb86bdfd-fmkvd   1/1     Running   0          8d
    kube-system     coredns-d798c9dd-ljjnf                    1/1     Running   0          8d

    Result: You have confirmed that you can access the cluster with kubectl and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html b/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html index 898493953e7..ca711296b64 100644 --- a/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html +++ b/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html @@ -5,13 +5,13 @@ Setting up a High-availability RKE Kubernetes Cluster | Rancher Manager - +
    Version: v2.6

    Setting up a High-availability RKE Kubernetes Cluster

    This section describes how to install a Kubernetes cluster. This cluster should be dedicated to run only the Rancher server.

    note

    Rancher can run on any Kubernetes cluster, included hosted Kubernetes solutions such as Amazon EKS. The below instructions represent only one possible way to install Kubernetes.

    For systems without direct internet access, refer to Air Gap: Kubernetes install.

    Single-node Installation Tip:

    In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node RKE cluster, configure only one node in the cluster.yml . The single node should have all three roles: etcd, controlplane, and worker.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Installing Kubernetes

    Required CLI Tools​

    Install kubectl, a Kubernetes command-line tool.

    Also install RKE, the Rancher Kubernetes Engine, a Kubernetes distribution and command-line tool.

    1. Create the cluster configuration file​

    In this section, you will create a Kubernetes cluster configuration file called rancher-cluster.yml. In a later step, when you set up the cluster with an RKE command, it will use this file to install Kubernetes on your nodes.

    Using the sample below as a guide, create the rancher-cluster.yml file. Replace the IP addresses in the nodes list with the IP address or DNS names of the 3 nodes you created.

    If your node has public and internal addresses, it is recommended to set the internal_address: so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the internal_address: if you want to use self-referencing security groups or firewalls.

    RKE will need to connect to each node over SSH, and it will look for a private key in the default location of ~/.ssh/id_rsa. If your private key for a certain node is in a different location than the default, you will also need to configure the ssh_key_path option for that node.

    nodes:
      - address: 165.227.114.63
        internal_address: 172.16.22.12
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.116.167
        internal_address: 172.16.32.37
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.127.226
        internal_address: 172.16.42.73
        user: ubuntu
        role: [controlplane, worker, etcd]

    services:
      etcd:
        snapshot: true
        creation: 6h
        retention: 24h

    # Required for external TLS termination with
    # ingress-nginx v0.22+
    ingress:
      provider: nginx
      options:
        use-forwarded-headers: "true"
    Common RKE Nodes Options
    OptionRequiredDescription
    addressyesThe public DNS or IP address
    useryesA user that can run docker commands
    roleyesList of Kubernetes roles assigned to the node
    internal_addressnoThe private DNS or IP address for internal cluster traffic
    ssh_key_pathnoPath to SSH private key used to authenticate to the node (defaults to ~/.ssh/id_rsa)
    Advanced Configurations:

    RKE has many configuration options for customizing the install to suit your specific environment.

    Please see the RKE Documentation for the full list of options and capabilities.

    For tuning your etcd cluster for larger Rancher installations, see the etcd settings guide.

    For more information regarding Dockershim support, refer to this page

    2. Run RKE​

    rke up --config ./rancher-cluster.yml

    When finished, it should end with the line: Finished building Kubernetes cluster successfully.

    3. Test Your Cluster​

    This section describes how to set up your workspace so that you can interact with this cluster using the kubectl command-line tool.

    Assuming you have installed kubectl, you need to place the kubeconfig file in a location where kubectl can reach it. The kubeconfig file contains the credentials necessary to access your cluster with kubectl.

    When you ran rke up, RKE should have created a kubeconfig file named kube_config_cluster.yml. This file has the credentials for kubectl and helm.

    note

    If you have used a different file name from rancher-cluster.yml, then the kube config file will be named kube_config_<FILE_NAME>.yml.

    Move this file to $HOME/.kube/config, or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_cluster.yml:

    export KUBECONFIG=$(pwd)/kube_config_cluster.yml

    Test your connectivity with kubectl and see if all your nodes are in Ready state:

    kubectl get nodes

    NAME                          STATUS    ROLES                      AGE       VERSION
    165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.13.5

    4. Check the Health of Your Cluster Pods​

    Check that all the required pods and containers are healthy are ready to continue.

    • Pods are in Running or Completed state.
    • READY column shows all the containers are running (i.e. 3/3) for pods with STATUS Running
    • Pods with STATUS Completed are run-once Jobs. For these pods READY should be 0/1.
    kubectl get pods --all-namespaces

    NAMESPACE       NAME                                      READY     STATUS      RESTARTS   AGE
    ingress-nginx   nginx-ingress-controller-tnsn4            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-tw2ht            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-v874b            1/1       Running     0          30s
    kube-system     canal-jp4hz                               3/3       Running     0          30s
    kube-system     canal-z2hg8                               3/3       Running     0          30s
    kube-system     canal-z6kpw                               3/3       Running     0          30s
    kube-system     kube-dns-7588d5b5f5-sf4vh                 3/3       Running     0          30s
    kube-system     kube-dns-autoscaler-5db9bbb766-jz2k6      1/1       Running     0          30s
    kube-system     metrics-server-97bc649d5-4rl2q            1/1       Running     0          30s
    kube-system     rke-ingress-controller-deploy-job-bhzgm   0/1       Completed   0          30s
    kube-system     rke-kubedns-addon-deploy-job-gl7t4        0/1       Completed   0          30s
    kube-system     rke-metrics-addon-deploy-job-7ljkc        0/1       Completed   0          30s
    kube-system     rke-network-plugin-deploy-job-6pbgj       0/1       Completed   0          30s

    This confirms that you have successfully installed a Kubernetes cluster that the Rancher server will run on.

    5. Save Your Files​

    Important:

    The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

    Save a copy of the following files in a secure location:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
    • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains credentials for full access to the cluster.

      The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher.
    note

    The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html b/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html index 7d977f48a4b..a15c1aecf65 100644 --- a/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html +++ b/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html @@ -5,13 +5,13 @@ Setting up a High-availability RKE2 Kubernetes Cluster for Rancher | Rancher Manager - +
    Version: v2.6

    Setting up a High-availability RKE2 Kubernetes Cluster for Rancher

    Tested on v2.5.6

    This section describes how to install a Kubernetes cluster according to the best practices for the Rancher server environment.

    Prerequisites

    These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in this section.

    Note that in order for RKE2 to work correctly with the load balancer, you need to set up two listeners: one for the supervisor on port 9345, and one for the Kubernetes API on port 6443.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the RKE2 version, use the INSTALL_RKE2_VERSION environment variable when running the RKE2 installation script.

    Installing Kubernetes

    1. Install Kubernetes and Set up the RKE2 Server​

    RKE2 server runs with embedded etcd so you will not need to set up an external datastore to run in HA mode.

    On the first node, you should set up the configuration file with your own pre-shared secret as the token. The token argument can be set on startup.

    If you do not specify a pre-shared secret, RKE2 will generate one and place it at /var/lib/rancher/rke2/server/node-token.

    To avoid certificate errors with the fixed registration address, you should launch the server with the tls-san parameter set. This option adds an additional hostname or IP as a Subject Alternative Name in the server's TLS cert, and it can be specified as a list if you would like to access via both the IP and the hostname.

    First, you must create the directory where the RKE2 config file is going to be placed:

    mkdir -p /etc/rancher/rke2/

    Next, create the RKE2 config file at /etc/rancher/rke2/config.yaml using the following example:

    token: my-shared-secret
    tls-san:
      - my-kubernetes-domain.com
      - another-kubernetes-domain.com

    After that, you need to run the install command and enable and start rke2:

    curl -sfL https://get.rke2.io | INSTALL_RKE2_CHANNEL=v1.20 sh -
    systemctl enable rke2-server.service
    systemctl start rke2-server.service

    1. To join the rest of the nodes, you need to configure each additional node with the same shared token or the one generated automatically. Here is an example of the configuration file:

          token: my-shared-secret
          server: https://<DNS-DOMAIN>:9345
          tls-san:
            - my-kubernetes-domain.com
            - another-kubernetes-domain.com

      After that, you need to run the installer and enable, then start, rke2:

          curl -sfL https://get.rke2.io | sh -
          systemctl enable rke2-server.service
          systemctl start rke2-server.service
    1. Repeat the same command on your third RKE2 server node.

    2. Confirm that RKE2 is Running​

    Once you've launched the rke2 server process on all server nodes, ensure that the cluster has come up properly with

    /var/lib/rancher/rke2/bin/kubectl \
            --kubeconfig /etc/rancher/rke2/rke2.yaml get nodes
    You should see your server nodes in the Ready state.

    Then test the health of the cluster pods:

    /var/lib/rancher/rke2/bin/kubectl \
            --kubeconfig /etc/rancher/rke2/rke2.yaml get pods --all-namespaces

    Result: You have successfully set up a RKE2 Kubernetes cluster.

    3. Save and Start Using the kubeconfig File​

    When you installed RKE2 on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/rke2/rke2.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/rke2/rke2.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your control-plane load balancer, on port 6443. (The RKE2 Kubernetes API Server uses port 6443, while the Rancher server will be served via the NGINX Ingress on ports 80 and 443.) Here is an example rke2.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your RKE2 cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the RKE2 documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    4. Check the Health of Your Cluster Pods​

    Now that you have set up the kubeconfig file, you can use kubectl to access the cluster from your local machine.

    Check that all the required pods and containers are healthy are ready to continue:

    /var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml get pods -A
    NAMESPACE     NAME                                                    READY   STATUS      RESTARTS   AGE
    kube-system   cloud-controller-manager-rke2-server-1                  1/1     Running     0          2m28s
    kube-system   cloud-controller-manager-rke2-server-2                  1/1     Running     0          61s
    kube-system   cloud-controller-manager-rke2-server-3                  1/1     Running     0          49s
    kube-system   etcd-rke2-server-1                                      1/1     Running     0          2m13s
    kube-system   etcd-rke2-server-2                                      1/1     Running     0          87s
    kube-system   etcd-rke2-server-3                                      1/1     Running     0          56s
    kube-system   helm-install-rke2-canal-hs6sx                           0/1     Completed   0          2m17s
    kube-system   helm-install-rke2-coredns-xmzm8                         0/1     Completed   0          2m17s
    kube-system   helm-install-rke2-ingress-nginx-flwnl                   0/1     Completed   0          2m17s
    kube-system   helm-install-rke2-metrics-server-7sggn                  0/1     Completed   0          2m17s
    kube-system   kube-apiserver-rke2-server-1                            1/1     Running     0          116s
    kube-system   kube-apiserver-rke2-server-2                            1/1     Running     0          66s
    kube-system   kube-apiserver-rke2-server-3                            1/1     Running     0          48s
    kube-system   kube-controller-manager-rke2-server-1                   1/1     Running     0          2m30s
    kube-system   kube-controller-manager-rke2-server-2                   1/1     Running     0          57s
    kube-system   kube-controller-manager-rke2-server-3                   1/1     Running     0          42s
    kube-system   kube-proxy-rke2-server-1                                1/1     Running     0          2m25s
    kube-system   kube-proxy-rke2-server-2                                1/1     Running     0          59s
    kube-system   kube-proxy-rke2-server-3                                1/1     Running     0          85s
    kube-system   kube-scheduler-rke2-server-1                            1/1     Running     0          2m30s
    kube-system   kube-scheduler-rke2-server-2                            1/1     Running     0          57s
    kube-system   kube-scheduler-rke2-server-3                            1/1     Running     0          42s
    kube-system   rke2-canal-b9lvm                                        2/2     Running     0          91s
    kube-system   rke2-canal-khwp2                                        2/2     Running     0          2m5s
    kube-system   rke2-canal-swfmq                                        2/2     Running     0          105s
    kube-system   rke2-coredns-rke2-coredns-547d5499cb-6tvwb              1/1     Running     0          92s
    kube-system   rke2-coredns-rke2-coredns-547d5499cb-rdttj              1/1     Running     0          2m8s
    kube-system   rke2-coredns-rke2-coredns-autoscaler-65c9bb465d-85sq5   1/1     Running     0          2m8s
    kube-system   rke2-ingress-nginx-controller-69qxc                     1/1     Running     0          52s
    kube-system   rke2-ingress-nginx-controller-7hprp                     1/1     Running     0          52s
    kube-system   rke2-ingress-nginx-controller-x658h                     1/1     Running     0          52s
    kube-system   rke2-metrics-server-6564db4569-vdfkn                    1/1     Running     0          66s

    Result: You have confirmed that you can access the cluster with kubectl and the RKE2 cluster is running successfully. Now the Rancher management server can be installed on the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html index 92e654a8775..4538df1e859 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html @@ -5,13 +5,13 @@ Recommended Cluster Architecture | Rancher Manager - +
    Version: v2.6

    Recommended Cluster Architecture

    There are three roles that can be assigned to nodes: etcd, controlplane and worker.

    Separating Worker Nodes from Nodes with Other Roles​

    When designing your cluster(s), you have two options:

    • Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the port requirements.
    • Assign the etcd and controlplane roles to the same nodes. These nodes must meet the hardware requirements for both roles.

    In either case, the worker role should not be used or added to nodes with the etcd or controlplane role.

    Therefore, each node should have one of the following role configurations:

    • etcd
    • controlplane
    • Both etcd and controlplane
    • worker

    The cluster should have:

    • At least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • At least two nodes with the role controlplane for master component high availability.
    • At least two nodes with the role worker for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    Number of Controlplane Nodes​

    Adding more than one node with the controlplane role makes every master component highly available.

    Number of etcd Nodes​

    The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the etcd role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an etcd node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.

    Nodes with etcd roleMajorityFailure Tolerance
    110
    220
    321
    431
    532
    642
    743
    853
    954

    References:

    Number of Worker Nodes​

    Adding more than one node with the worker role will make sure your workloads can be rescheduled if a node fails.

    Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications​

    You may have noticed that our Kubernetes Install instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the worker role. However, for your Rancher installation, this three node cluster is valid, because:

    • It allows one etcd node failure.
    • It maintains multiple instances of the master components by having multiple controlplane nodes.
    • No other workloads than Rancher itself should be created on this cluster.

    References​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html index 9fd5706fd8d..06ec5b74a9e 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html @@ -5,13 +5,13 @@ Roles for Nodes in Kubernetes | Rancher Manager - +
    Version: v2.6

    Roles for Nodes in Kubernetes

    This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster.

    This diagram is applicable to Kubernetes clusters launched with Rancher using RKE..

    Cluster diagram

    Lines show the traffic flow between components. Colors are used purely for visual aid

    etcd​

    Nodes with the etcd role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.

    note

    Nodes with the etcd role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    controlplane​

    Nodes with the controlplane role run the Kubernetes master components (excluding etcd, as it's a separate role). See Kubernetes: Master Components for a detailed list of components.

    note

    Nodes with the controlplane role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    kube-apiserver​

    The Kubernetes API server (kube-apiserver) scales horizontally. Each node with the role controlplane will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.

    kube-controller-manager​

    The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the kube-controller-manager will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    kube-scheduler​

    The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the kube-scheduler will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    worker​

    Nodes with the worker role run the Kubernetes node components. See Kubernetes: Node Components for a detailed list of components.

    References​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html index abfb21ba8d8..8b115232b40 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html @@ -5,13 +5,13 @@ Rancher Agents | Rancher Manager - +
    Version: v2.6

    Rancher Agents

    There are two different agent resources deployed on Rancher managed clusters:

    For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the architecture

    cattle-cluster-agent​

    The cattle-cluster-agent is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The cattle-cluster-agent is deployed using a Deployment resource.

    cattle-node-agent​

    The cattle-node-agent is used to interact with nodes in a Rancher Launched Kubernetes cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node. The cattle-node-agent is used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when cattle-cluster-agent is unavailable.

    Scheduling rules​

    The cattle-cluster-agent uses a fixed fixed set of tolerations (listed below, if no controlplane nodes are visible in the cluster) or dynamically added tolerations based on taints applied to the controlplane nodes. This structure allows for Taint based Evictions to work properly for cattle-cluster-agent. The default tolerations are described below. If controlplane nodes are present the cluster, the tolerations will be replaced with tolerations matching the taints on the controlplane nodes.

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneNote: These are the default tolerations, and will be replaced by tolerations matching taints applied to controlplane nodes.

    effect:NoSchedule
    key:node-role.kubernetes.io/controlplane
    value:true

    effect:NoSchedule
    key:node-role.kubernetes.io/control-plane
    operator:Exists

    effect:NoSchedule
    key:node-role.kubernetes.io/master
    operator:Exists
    cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

    The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. When there are no controlplane nodes visible in the cluster (this is usually the case when using Clusters from Hosted Kubernetes Providers), you can add the label cattle.io/cluster-agent=true on a node to prefer scheduling the cattle-cluster-agent pod to that node.

    See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

    The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

    WeightExpression
    100node-role.kubernetes.io/controlplane:In:"true"
    100node-role.kubernetes.io/control-plane:In:"true"
    100node-role.kubernetes.io/master:In:"true"
    1cattle.io/cluster-agent:In:"true"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/rke1-vs-rke2-differences.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/rke1-vs-rke2-differences.html index 175aec35fb0..c8035ab521e 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/rke1-vs-rke2-differences.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/rke1-vs-rke2-differences.html @@ -5,13 +5,13 @@ Behavior Differences Between RKE1 and RKE2 | Rancher Manager - +
    Version: v2.6

    Behavior Differences Between RKE1 and RKE2

    RKE2, also known as RKE Government, is a Kubernetes distribution that focuses on security and compliance for U.S. Federal Government entities. It is considered the next iteration of the Rancher Kubernetes Engine, now known as RKE1.

    RKE1 and RKE2 have several slight behavioral differences to note, and this page will highlight some of these at a high level.

    Control Plane Components​

    RKE1 uses Docker for deploying and managing control plane components, and it also uses Docker as the container runtime for Kubernetes. By contrast, RKE2 launches control plane components as static pods that are managed by the kubelet. RKE2's container runtime is containerd, which allows things such as container registry mirroring (RKE1 with Docker does not).

    Cluster API​

    RKE2/K3s provisioning is built on top of the Cluster API (CAPI) upstream framework which often makes RKE2-provisioned clusters behave differently than RKE1-provisioned clusters.

    When you make changes to your cluster configuration in RKE2, this may result in nodes reprovisioning. This is controlled by CAPI controllers and not by Rancher itself. Note that for etcd nodes, the same behavior does not apply.

    The following are some specific example configuration changes that may cause the described behavior:

    • When editing the cluster and enabling drain before delete, the existing control plane nodes and worker are deleted and new nodes are created.

    • When nodes are being provisioned and a scale down operation is performed, rather than scaling down the desired number of nodes, it is possible that the currently provisioning nodes get deleted and new nodes are provisioned to reach the desired node count. Please note that this is a bug in Cluster API, and it will be fixed in an upcoming release. Once fixed, Rancher will update the documentation.

    Users who are used to RKE1 provisioning should take note of this new RKE2 behavior which may be unexpected.

    Terminology​

    You will notice that some terms have changed or gone away going from RKE1 to RKE2. For example, in RKE1 provisioning, you use node templates; in RKE2 provisioning, you can configure your cluster node pools when creating or editing the cluster. Another example is that the term node pool in RKE1 is now known as machine pool in RKE2.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html index 916bc5d84a3..3062398e193 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html @@ -5,13 +5,13 @@ Setting up the Amazon Cloud Provider | Rancher Manager - +
    Version: v2.6

    Setting up the Amazon Cloud Provider

    When using the Amazon cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an AWS Elastic Load Balancer (ELB) when choosing Layer-4 Load Balancer in Port Mapping or when launching a Service with type: LoadBalancer.
    • Persistent Volumes: Allows you to use AWS Elastic Block Stores (EBS) for persistent volumes.

    See cloud-provider-aws README for all information regarding the Amazon cloud provider.

    To set up the Amazon cloud provider,

    1. Create an IAM role and attach to the instances
    2. Configure the ClusterID

    1. Create an IAM Role and attach to the instances​

    All nodes added to the cluster must be able to interact with EC2 so that they can create and remove resources. You can enable this interaction by using an IAM role attached to the instance. See Amazon documentation: Creating an IAM Role how to create an IAM role. There are two example policies:

    • The first policy is for the nodes with the controlplane role. These nodes have to be able to create/remove EC2 resources. The following IAM policy is an example, please remove any unneeded permissions for your use case.
    • The second policy is for the nodes with the etcd or worker role. These nodes only have to be able to retrieve information from EC2.

    While creating an Amazon EC2 cluster, you must fill in the IAM Instance Profile Name (not ARN) of the created IAM role when creating the Node Template.

    While creating a Custom cluster, you must manually attach the IAM role to the instance(s).

    IAM Policy for nodes with the controlplane role:

    {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "autoscaling:DescribeAutoScalingGroups",
          "autoscaling:DescribeLaunchConfigurations",
          "autoscaling:DescribeTags",
          "ec2:DescribeInstances",
          "ec2:DescribeRegions",
          "ec2:DescribeRouteTables",
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeSubnets",
          "ec2:DescribeVolumes",
          "ec2:CreateSecurityGroup",
          "ec2:CreateTags",
          "ec2:CreateVolume",
          "ec2:ModifyInstanceAttribute",
          "ec2:ModifyVolume",
          "ec2:AttachVolume",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:CreateRoute",
          "ec2:DeleteRoute",
          "ec2:DeleteSecurityGroup",
          "ec2:DeleteVolume",
          "ec2:DetachVolume",
          "ec2:RevokeSecurityGroupIngress",
          "ec2:DescribeVpcs",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:AttachLoadBalancerToSubnets",
          "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancerPolicy",
          "elasticloadbalancing:CreateLoadBalancerListeners",
          "elasticloadbalancing:ConfigureHealthCheck",
          "elasticloadbalancing:DeleteLoadBalancer",
          "elasticloadbalancing:DeleteLoadBalancerListeners",
          "elasticloadbalancing:DescribeLoadBalancers",
          "elasticloadbalancing:DescribeLoadBalancerAttributes",
          "elasticloadbalancing:DetachLoadBalancerFromSubnets",
          "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
          "elasticloadbalancing:ModifyLoadBalancerAttributes",
          "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
          "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:CreateListener",
          "elasticloadbalancing:CreateTargetGroup",
          "elasticloadbalancing:DeleteListener",
          "elasticloadbalancing:DeleteTargetGroup",
          "elasticloadbalancing:DescribeListeners",
          "elasticloadbalancing:DescribeLoadBalancerPolicies",
          "elasticloadbalancing:DescribeTargetGroups",
          "elasticloadbalancing:DescribeTargetHealth",
          "elasticloadbalancing:ModifyListener",
          "elasticloadbalancing:ModifyTargetGroup",
          "elasticloadbalancing:RegisterTargets",
          "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
          "iam:CreateServiceLinkedRole",
          "kms:DescribeKey"
        ],
        "Resource": [
          "*"
        ]
      }
    ]
    }

    IAM policy for nodes with the etcd or worker role:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "ec2:DescribeRegions",
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:GetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:BatchGetImage"
            ],
            "Resource": "*"
        }
    ]
    }

    2. Configure the ClusterID​

    The following resources need to tagged with a ClusterID:

    • Nodes: All hosts added in Rancher.
    • Subnet: The subnet used for your cluster.
    • Security Group: The security group used for your cluster.
    note

    Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB).

    When you create an Amazon EC2 Cluster, the ClusterID is automatically configured for the created nodes. Other resources still need to be tagged manually.

    Use the following tag:

    Key = kubernetes.io/cluster/CLUSTERID Value = owned

    CLUSTERID can be any string you like, as long as it is equal across all tags set.

    Setting the value of the tag to owned tells the cluster that all resources with this tag are owned and managed by this cluster. If you share resources between clusters, you can change the tag to:

    Key = kubernetes.io/cluster/CLUSTERID Value = shared.

    Using Amazon Elastic Container Registry (ECR)​

    The kubelet component has the ability to automatically obtain ECR credentials, when the IAM profile mentioned in Create an IAM Role and attach to the instances is attached to the instance(s). When using a Kubernetes version older than v1.15.0, the Amazon cloud provider needs be configured in the cluster. Starting with Kubernetes version v1.15.0, the kubelet can obtain ECR credentials without having the Amazon cloud provider configured in the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html index 30c140356ed..d6bf8d6c960 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html @@ -5,14 +5,14 @@ Setting up the Azure Cloud Provider | Rancher Manager - +
    Version: v2.6

    Setting up the Azure Cloud Provider

    When using the Azure cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an Azure Load Balancer within a specific Network Security Group.

    • Persistent Volumes: Supports using Azure Blob disks and Azure Managed Disks with standard and premium storage accounts.

    • Network Storage: Support Azure Files via CIFS mounts.

    The following account types are not supported for Azure Subscriptions:

    • Single tenant accounts (i.e. accounts with no subscriptions).
    • Multi-subscription accounts.

    Prerequisites for RKE and RKE2

    To set up the Azure cloud provider for both RKE and RKE2, the following credentials need to be configured:

    1. Set up the Azure Tenant ID
    2. Set up the Azure Client ID and Azure Client Secret
    3. Configure App Registration Permissions
    4. Set up Azure Network Security Group Name

    1. Set up the Azure Tenant ID​

    Visit Azure portal, login and go to Azure Active Directory and select Properties. Your Directory ID is your Tenant ID (tenantID).

    If you want to use the Azure CLI, you can run the command az account show to get the information.

    2. Set up the Azure Client ID and Azure Client Secret​

    Visit Azure portal, login and follow the steps below to create an App Registration and the corresponding Azure Client ID (aadClientId) and Azure Client Secret (aadClientSecret).

    1. Select Azure Active Directory.
    2. Select App registrations.
    3. Select New application registration.
    4. Choose a Name, select Web app / API as Application Type and a Sign-on URL which can be anything in this case.
    5. Select Create.

    In the App registrations view, you should see your created App registration. The value shown in the column APPLICATION ID is what you need to use as Azure Client ID.

    The next step is to generate the Azure Client Secret:

    1. Open your created App registration.
    2. In the Settings view, open Keys.
    3. Enter a Key description, select an expiration time and select Save.
    4. The generated value shown in the column Value is what you need to use as Azure Client Secret. This value will only be shown once.

    3. Configure App Registration Permissions​

    The last thing you will need to do, is assign the appropriate permissions to your App registration.

    1. Go to More services, search for Subscriptions and open it.
    2. Open Access control (IAM).
    3. Select Add.
    4. For Role, select Contributor.
    5. For Select, select your created App registration name.
    6. Select Save.

    4. Set up Azure Network Security Group Name​

    A custom Azure Network Security Group (securityGroupName) is needed to allow Azure Load Balancers to work.

    If you provision hosts using Rancher Machine Azure driver, you will need to edit them manually to assign them to this Network Security Group.

    You should already assign custom hosts to this Network Security Group during provisioning.

    Only hosts expected to be load balancer back ends need to be in this group.

    RKE2 Cluster Set-up in Rancher

    1. Choose "Azure" from the Cloud Provider drop-down in the Cluster Configuration section.

      • Supply the Cloud Provider Configuration. Note that Rancher will automatically create a new Network Security Group, Resource Group, Availability Set, Subnet, and Virtual Network. If you already have some or all of these created, you will need to specify them before creating the cluster.
      • You can click on "Show Advanced" to see more of these automatically generated names and update them if necessary. Your Cloud Provider Configuration must match the fields in the Machine Pools section. If you have multiple pools, they must all use the same Resource Group, Availability Set, Subnet, Virtual Network, and Network Security Group.
      • An example is provided below. You will modify it as needed.
      Example Cloud Provider Config
      {
          "cloud":"AzurePublicCloud",
          "tenantId": "YOUR TENANTID HERE",
          "aadClientId": "YOUR AADCLIENTID HERE",
          "aadClientSecret": "YOUR AADCLIENTSECRET HERE",
          "subscriptionId": "YOUR SUBSCRIPTIONID HERE",
          "resourceGroup": "docker-machine",
          "location": "westus",
          "subnetName": "docker-machine",
          "securityGroupName": "rancher-managed-KA4jV9V2",
          "securityGroupResourceGroup": "docker-machine",
          "vnetName": "docker-machine-vnet",
          "vnetResourceGroup": "docker-machine",
          "primaryAvailabilitySetName": "docker-machine",
          "routeTableResourceGroup": "docker-machine",
          "cloudProviderBackoff": false,
          "useManagedIdentityExtension": false,
          "useInstanceMetadata": true
      }

    3. Under the Cluster Configuration > Advanced section, click Add under Additional Controller Manager Args and add this flag: --configure-cloud-routes=false

    4. Click the Create button to submit the form and create the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html index aad373a4777..99e68a4c687 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html @@ -5,13 +5,13 @@ Setting up the Google Compute Engine Cloud Provider | Rancher Manager - +
    Version: v2.6

    Setting up the Google Compute Engine Cloud Provider

    In this section, you'll learn how to enable the Google Compute Engine (GCE) cloud provider for custom clusters in Rancher. A custom cluster is one in which Rancher installs Kubernetes on existing nodes.

    The official Kubernetes documentation for the GCE cloud provider is here.

    Prerequisites:

    The service account of Identity and API access on GCE needs the Computer Admin permission.

    If you are using Calico,

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, go to the custom cluster and click *⋮ > Edit YAML. Enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        network:
          options:
            calico_cloud_provider: "gce"
          plugin: "calico"

    If you are using Canal or Flannel,

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, go to the custom cluster and click *⋮ > Edit YAML. Enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        services:
          kube_controller:
            extra_args:
              configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html index 7ae1dbefc95..1cf0d62196f 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html @@ -5,13 +5,13 @@ How to Configure In-tree vSphere Cloud Provider | Rancher Manager - +
    Version: v2.6

    How to Configure In-tree vSphere Cloud Provider

    To set up the in-tree vSphere cloud provider, follow these steps while creating the vSphere cluster in Rancher:

    1. Set Cloud Provider option to Custom or Custom (In-Tree).

    2. Click on Edit as YAML

    3. Insert the following structure to the pre-populated cluster YAML. This structure must be placed under rancher_kubernetes_engine_config. Note that the name must be set to vsphere.

      rancher_kubernetes_engine_config:
        cloud_provider:
            name: vsphere
            vsphereCloudProvider:
                [Insert provider configuration]

    Rancher uses RKE (the Rancher Kubernetes Engine) to provision Kubernetes clusters. Refer to the vSphere configuration reference in the RKE documentation for details about the properties of the vsphereCloudProvider directive.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html index 63c2b117a70..c55c87e96d7 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html @@ -5,13 +5,13 @@ How to Configure Out-of-tree vSphere Cloud Provider | Rancher Manager - +
    Version: v2.6

    How to Configure Out-of-tree vSphere Cloud Provider

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after bringing up a cluster.

    Prerequisites

    The vSphere versions supported:

    • 6.7u3
    • 7.0u1 or higher.

    The Kubernetes version must be 1.19 or higher.

    Using the vSphere out-of-tree cloud provider requires Linux nodes and is not supported on Windows.

    Installation

    The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI).

    1. Create a vSphere cluster​

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click VMware vSphere or Custom.
    4. On the Basics tab in the Cluster Configuration section, set the Cloud Provider to vSphere.
    5. In the Add-On Config tab, the vSphere Cloud Provider (CPI) and Storage Provider (CSI) options.
    6. Finish creating your cluster.

    2. Install the CPI plugin​

    1. Click ☰ > Cluster Management.

    2. Go to the cluster where the vSphere CPI plugin will be installed and click Explore.

    3. Click Apps & Marketplace > Charts.

    4. Click vSphere CPI.

    5. Fill out the required vCenter details.

    6. vSphere CPI initializes all nodes with ProviderID which is needed by the vSphere CSI driver. Check if all nodes are initialized with the ProviderID before installing CSI driver with the following command:

      kubectl describe nodes | grep "ProviderID"

    3. Installing the CSI plugin​

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where the vSphere CSI plugin will be installed and click Explore.
    3. Click Apps & Marketplace > Charts.
    4. Click vSphere CSI.
    5. Click Install.
    6. Fill out the required vCenter details. On the Features tab, set Enable CSI Migration to false.
    7. On the Storage tab, fill out the details for the StorageClass. This chart creates a StorageClass with the csi.vsphere.vmware.com as the provisioner.
    8. Click Install.

    Using the CSI driver for provisioning volumes

    The CSI chart by default creates a storageClass.

    If that option was not selected while launching the chart, create a storageClass with the csi.vsphere.vmware.com as the provisioner.

    All volumes provisioned using this StorageClass will get provisioned by the CSI driver.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html index 6212833a1d4..3a5373d2ced 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html @@ -5,13 +5,13 @@ Migrating vSphere In-tree Volumes to CSI | Rancher Manager - +
    Version: v2.6

    Migrating vSphere In-tree Volumes to CSI

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    This page covers how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration.

    It follows the steps provided in the official vSphere migration documentation and provides the steps to be performed in Rancher.

    Cloud-config Format Limitation​

    Existing volumes that were provisioned using the following cloud-config format will NOT get migrated due to an existing bug in vsphere CSI.

    If the cloud-config has this format for datastore and resource pool path, vsphere CSI driver cannot recognize it:

    default-datastore: </datacenter>/datastore/<default-datastore-name>
    resourcepool-path: "</datacenter>/host/<cluster-name>/Resources/<resource-pool-name>"

    Volumes provisioned with the in-tree provider using the following format will get migrated correctly:

    default-datastore: <default-datastore-name>
    resourcepool-path: "<cluster-name>/Resources/<resource-pool-name>"

    Upstream bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628

    Rancher issue tracking this bug: https://github.com/rancher/rancher/issues/31105

    Prerequisites

    • vSphere CSI Migration requires vSphere 7.0u1. In order to be able to manage existing in-tree vSphere volumes, upgrade vSphere to 7.0u1.
    • The Kubernetes version must be 1.19 or higher.

    Migration

    1. Install the CPI plugin​

    Before installing CPI, we need to taint all nodes with node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule.

    This can be done by running the following commands:

    curl -O https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh

    Or:

    wget https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh
    chmod +x taints.sh
    ./taints.sh <path to kubeconfig if running the command outside the cluster>

    Once all nodes are tainted by the running the script, launch the Helm vSphere CPI chart.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where the vSphere CPI chart will be installed and click Explore.
    3. Click Apps & Marketplace > Charts.
    4. Click vSphere CPI..
    5. Click Install.
    6. Fill out the required vCenter details and click Install.

    vSphere CPI initializes all nodes with ProviderID, which is needed by the vSphere CSI driver.

    Check if all nodes are initialized with the ProviderID with the following command:

    kubectl describe nodes | grep "ProviderID"

    2. Install the CSI driver​

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where the vSphere CSI chart will be installed and click Explore.
    3. Click Apps & Marketplace > Charts.
    4. Click vSphere CSI..
    5. Click Install.
    6. Fill out the required vCenter details and click Install.
    7. Check Customize Helm options before install and click Next.
    8. On the Features tab, check Enable CSI Migration.
    9. Optionally, go to the Storage tab and set up a datastore. This chart creates a StorageClass with the csi.vsphere.vmware.com as the provisioner. You can provide the URL of the datastore to be used for CSI volume provisioning while creating this StorageClass. The datastore URL can be found in the vSphere client by selecting the datastore and going to the Summary tab. Fill out the details for the StorageClass.
    10. Click Install.

    3. Edit the cluster to enable CSI migration feature flags​

    1. While editing the cluster, if the Kubernetes version is less than 1.19, select Kubernetes version 1.19 or higher from the Kubernetes Version dropdown.

    2. For enabling feature flags, click on "Edit as YAML", and add the following under kube-controller and kubelet:

        extra_args:
          feature-gates: "CSIMigration=true,CSIMigrationvSphere=true"

    4. Drain worker nodes​

    Worker nodes must be drained during the upgrade before changing the kubelet and kube-controller-manager args.

    1. Click ☰ > Cluster Management.
    2. Go to the cluster where you will drain worker nodes and click ⋮ > Edit Config.
    3. In the Advanced Options section, set the field Maximum Worker Nodes Unavailable to 1.
    4. To drain the nodes during upgrade, select Drain Nodes > Yes.
    5. Set Force and Delete Local Data to true.
    6. Click Save to upgrade the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html index 5e3c46b56d2..9aa966ede39 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html @@ -5,13 +5,13 @@ Creating a DigitalOcean Cluster | Rancher Manager - +
    Version: v2.6

    Creating a DigitalOcean Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in DigitalOcean.

    First, you will set up your DigitalOcean cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in DigitalOcean.

    Then you will create a DigitalOcean cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click DigitalOcean.
    5. Enter your Digital Ocean credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for DigitalOcean will allow Rancher to provision new nodes in DigitalOcean. Node templates can be reused for other clusters.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Click Add Template.
    4. Click DigitalOcean.
    5. Fill out a node template for DigitalOcean. For help filling out the form, refer to DigitalOcean Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click DigitalOcean.
    4. Enter a Cluster Name.
    5. Add one or more node pools to your cluster. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.
    6. In the Cluster Configuration section, choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    8. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html index 51b5bb179aa..cdf92fe119e 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html @@ -5,13 +5,13 @@ Creating an Amazon EC2 Cluster | Rancher Manager - +
    Version: v2.6

    Creating an Amazon EC2 Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in Amazon EC2.

    First, you will set up your EC2 cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in EC2.

    Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    Prerequisites​

    Creating an EC2 Cluster

    The steps to create a cluster differ based on your Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials and information from EC2
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click Amazon.
    5. Enter a name for the cloud credential.
    6. In the Default Region field, select the AWS region where your cluster nodes will be located.
    7. Enter your AWS EC2 Access Key and Secret Key.
    8. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials and information from EC2​

    Creating a node template for EC2 will allow Rancher to provision new nodes in EC2. Node templates can be reused for other clusters.

    1. Click ☰ > Cluster Management.

    2. Click RKE1 Configuration > Node Templates

    3. Click Add Template.

    4. Fill out a node template for EC2. For help filling out the form, refer to EC2 Node Template Configuration.

    5. Click Create.

      note

      If you want to use the dual-stack feature, there are additional requirements that must be taken into consideration.

    3. Create a cluster with node pools using the node template​

    Add one or more node pools to your cluster. For more information about node pools, see this section.

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, click Create.

    3. Click Amazon EC2.

    4. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.

    5. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    6. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. Refer to Selecting Cloud Providers to configure the Kubernetes Cloud Provider. For help configuring the cluster, refer to the RKE cluster configuration reference.

      note

      If you want to use the dual-stack feature, there are additional requirements that must be taken into consideration.

    7. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    IAM Policies

    Example IAM Policy​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy with PassRole​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "iam:PassRole",
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*",
                    "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy to allow encrypted EBS volumes​

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:Decrypt",
            "kms:GenerateDataKeyWithoutPlaintext",
            "kms:Encrypt",
            "kms:DescribeKey",
            "kms:CreateGrant",
            "ec2:DetachVolume",
            "ec2:AttachVolume",
            "ec2:DeleteSnapshot",
            "ec2:DeleteTags",
            "ec2:CreateTags",
            "ec2:CreateVolume",
            "ec2:DeleteVolume",
            "ec2:CreateSnapshot"
          ],
          "Resource": [
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*",
            "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeInstances",
            "ec2:DescribeTags",
            "ec2:DescribeVolumes",
            "ec2:DescribeSnapshots"
          ],
          "Resource": "*"
        }
      ]
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html index 761bd9f18d6..987da0e12d5 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html @@ -5,13 +5,13 @@ Creating an Azure Cluster | Rancher Manager - +
    Version: v2.6

    Creating an Azure Cluster

    In this section, you'll learn how to install an RKE Kubernetes cluster in Azure through Rancher.

    First, you will set up your Azure cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in Azure.

    Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    caution

    When the Rancher RKE cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows:

    • Terminate the SSL/TLS on the internal load balancer
    • Use the L7 load balancer

    For more information, refer to the documentation on Azure load balancer limitations.

    For more information on configuring the Kubernetes cluster that Rancher will install on the Azure nodes, refer to the RKE cluster configuration reference.

    For more information on configuring Azure node templates, refer to the Azure node template configuration reference.

    Preparation in Azure

    Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription.

    To do this, we will first create a new Azure service principal (SP) in Azure Active Directory (AD), which, in Azure, is an application user who has permission to manage Azure resources.

    The following is a template az cli script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope:

    az ad sp create-for-rbac \
      --name="<Rancher ServicePrincipal name>" \
      --role="Contributor" \
      --scopes="/subscriptions/<subscription Id>"

    The creation of this service principal returns three pieces of identification information, The application ID, also called the client ID, and The client secret. This information will be used when you create a node template for Azure.

    Creating an Azure Cluster

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click Azure.
    5. Enter your Azure credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for Azure will allow Rancher to provision new nodes in Azure. Node templates can be reused for other clusters.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Click Add Template.
    4. Click Azure.
    5. Fill out a node template for Azure. For help filling out the form, refer to Azure Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in Azure.

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click Azure.
    4. Enter a Cluster Name.
    5. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices, see this section.
    6. In the Cluster Configuration to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    8. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.html index e9fcda566db..05911baf3c4 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/nutanix/provision-kubernetes-clusters-in-aos.html @@ -5,13 +5,13 @@ Provisioning Kubernetes Clusters in Nutanix AOS | Rancher Manager - +
    Version: v2.6

    Provisioning Kubernetes Clusters in Nutanix AOS

    To use Rancher to install an RKE Kubernetes cluster in Nutanix AOS (AHV):

    1. Locate Rancher's built-in Nutanix node driver and activate it.

    2. Create a node template, which Rancher will use to provision nodes in Nutanix AOS.

    3. Create a Nutanix AOS cluster in Rancher. When configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    For details on configuring the Nutanix AOS node template, refer to the Nutanix AOS node template configuration reference.

    For details on configuring RKE Kubernetes clusters in Rancher, refer to the cluster configuration reference.

    Preparation in Nutanix AOS

    The following sections describe the requirements for setting up Nutanix AOS so that Rancher can provision VMs and clusters.

    note

    The node templates are documented and tested with Nutanix AOS version 5.20.2 and 6.0.1.

    Create Credentials in Nutanix AOS​

    Before proceeding to create a cluster, you must ensure that you have a Nutanix Prism Central user account with admin permissions. When you set up a node template, the template will need to use these credentials.

    Network Permissions​

    You must ensure that the hosts running the Rancher server are able to establish the following network connections:

    • To the Nutanix Prism Central API (usually port 9440/TCP).
    • To port 22/TCP and 2376/TCP on the created VMs

    See Node Networking Requirements for a detailed list of port requirements applicable for creating nodes on an infrastructure provider.

    VM-VM Anti-Affinity Policies​

    Setting up VM-VM Anti-Affinity Policies is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate AHV hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes.

    Creating a Nutanix AOS Cluster

    1. Create a node template
    2. Create a cluster with node pools using the node template

    1. Create a node template​

    Creating a node template for Nutanix AOS will allow Rancher to provision new nodes in Nutanix AOS. Node templates can be reused for other clusters.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Click Create.
    4. Click Add Template.
    5. Click Nutanix.
    6. Fill out a node template for Nutanix AOS. For help filling out the form, refer to the Nutanix AOS node template configuration reference..
    7. Click Create.

    2. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in Nutanix AOS.

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click Nutanix.
    4. Enter a Cluster Name, then click Continue.
    5. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users who can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used, and whether you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to the nodes, see this section.
    8. Review your options to confirm they're correct. Then click Create.

    Result: Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.

    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.html index ec1f619b059..e7518ca790d 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-a-vm-template.html @@ -5,13 +5,13 @@ Creating a vSphere Virtual Machine Template | Rancher Manager - +
    Version: v2.6

    Creating a vSphere Virtual Machine Template

    Creating virtual machines in a repeatable and reliable fashion can often be difficult. VMware vSphere offers the ability to build one VM that can then be converted to a template. The template can then be used to create identically configured VMs. Rancher leverages this capability within node pools to create identical RKE1 and RKE2 nodes.

    In order to leverage the template to create new VMs, Rancher has some specific requirements that the VM must have pre-installed. After you configure the VM with these requirements, you will next need to prepare the VM before creating the template. Finally, once preparation is complete, the VM can be converted to a template and moved into a content library, ready for Rancher node pool usage.

    Requirements​

    There is specific tooling required for both Linux and Windows VMs to be usable by the vSphere node driver. The most critical dependency is cloud-init for Linux and cloudbase-init for Windows. Both of these are used for provisioning the VMs by configuring the hostname and by setting up the SSH access and the default Rancher user. Users can add additional content to these as desired if other configuration is needed. In addition, other requirements are listed below for reference.

    note

    If you have any specific firewall rules or configuration, you will need to add this to the VM before creating a template.

    Linux Dependencies​

    The packages that need to be installed on the template are listed below. These will have slightly different names based on distribution; some distributions ship these by default, for example.

    • curl
    • wget
    • git
    • net-tools
    • unzip
    • apparmor-parser
    • ca-certificates
    • cloud-init
    • cloud-guest-utils
    • cloud-image-utils
    • growpart
    • cloud-initramfs-growroot
    • open-iscsi
    • openssh-server
    • open-vm-tools

    Windows Dependencies​

    The list of packages that need to be installed on the template is as follows:

    About the configuration for Windows templates varies between RKE1 and RKE2:
    • RKE1 leverages Docker, so any RKE1 templates need to have Docker EE pre-installed as well
    • RKE2 does not require Docker EE, and thus it does not need to be installed

    Creating a Template​

    You may either manually create your VM or you can utilize other alternatives to create your VM.

    Manual Creation​

    1. Manually create your VM by following these instructions from VMware. Once you have a VM running, you can manually install the dependencies listed above to configure the VM correctly for the vSphere node driver.
    2. Customize as needed based on your specific environment and requirements.
    3. Proceed with the final preparation before creating your template.

    Alternatives to Manual Creation​

    Other alternative options to create VMs are listed below:

    Packer is a frequently-used alternative. Refer to this reference for examples of its usage with vSphere.

    Preparing Your VM​

    After creating a VM with all the required dependencies (and any additional required items), you must perform the most critical step next: preparing the VM to be turned into a template. This preparation will reset critical data such as the VM hostname, IPs, etc., to prevent that information from being brought into a new VM. If you fail to perform this step, you could create a VM with the same hostname, IP address, etc.

    Note that these preparatory steps differ between Linux and Windows.

    Linux Preparation​

    The commands below will reset your VM in Linux:

    # Cleaning logs.
    if [ -f /var/log/audit/audit.log ]; then
      cat /dev/null > /var/log/audit/audit.log
    fi
    if [ -f /var/log/wtmp ]; then
      cat /dev/null > /var/log/wtmp
    fi
    if [ -f /var/log/lastlog ]; then
      cat /dev/null > /var/log/lastlog
    fi

    # Cleaning udev rules.
    if [ -f /etc/udev/rules.d/70-persistent-net.rules ]; then
      rm /etc/udev/rules.d/70-persistent-net.rules
    fi

    # Cleaning the /tmp directories
    rm -rf /tmp/*
    rm -rf /var/tmp/*

    # Cleaning the SSH host keys
    rm -f /etc/ssh/ssh_host_*

    # Cleaning the machine-id
    truncate -s 0 /etc/machine-id
    rm /var/lib/dbus/machine-id
    ln -s /etc/machine-id /var/lib/dbus/machine-id

    # Cleaning the shell history
    unset HISTFILE
    history -cw
    echo > ~/.bash_history
    rm -fr /root/.bash_history

    # Truncating hostname, hosts, resolv.conf and setting hostname to localhost
    truncate -s 0 /etc/{hostname,hosts,resolv.conf}
    hostnamectl set-hostname localhost

    # Clean cloud-init
    cloud-init clean -s -l

    Windows Preparation​

    Windows has a utility called sysprep that is used to generalize an image and reset the same items listed above for Linux. The command is as follows:

    sysprep.exe /generalize /shutdown /oobe

    Converting to a Template​

    1. Shut down and stop the VM.
    2. Right-click on the VM in the inventory list and select Template.
    3. Click on Convert to Template.

    Result: Once the process has completed, a template will be available for use.

    For additional information on converting a VM to a template, see the VMware guide.

    Moving to a Content library​

    Rancher has the ability to use templates provided by a content library. Content libraries store and manage content within vSphere, and they also offer the ability to publish and share that content.

    Below are some helpful links on content libraries:

    Other Resources​

    Here is a list of additional resources that may be useful:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html index be7ec1060f3..bbf1a7f1318 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html @@ -5,13 +5,13 @@ Creating Credentials in the vSphere Console | Rancher Manager - +
    Version: v2.6

    Creating Credentials in the vSphere Console

    This section describes how to create a vSphere username and password. You will need to provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere.

    The following table lists the permissions required for the vSphere user account:

    Privilege GroupOperations
    DatastoreAllocateSpace
    Browse
    FileManagement (Low level file operations)
    UpdateVirtualMachineFiles
    UpdateVirtualMachineMetadata
    GlobalSet custom attribute
    NetworkAssign
    ResourceAssignVMToPool
    Virtual MachineConfig (All)
    GuestOperations (All)
    Interact (All)
    Inventory (All)
    Provisioning (All)
    vSphere TaggingAssign or Unassign vSphere Tag
    Assign or Unassign vSphere Tag on Object

    The following steps create a role with the required privileges and then assign it to a new user in the vSphere console:

    1. From the vSphere console, go to the Administration page.

    2. Go to the Roles tab.

    3. Create a new role. Give it a name and select the privileges listed in the permissions table above.

    4. Go to the Users and Groups tab.

    5. Create a new user. Fill out the form and then click OK. Make sure to note the username and password, because you will need it when configuring node templates in Rancher.

    6. Go to the Global Permissions tab.

    7. Create a new Global Permission. Add the user you created earlier and assign it the role you created earlier. Click OK.

    Result: You now have credentials that Rancher can use to manipulate vSphere resources.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html index 1a9af2c416e..83c4b8b958e 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html @@ -5,13 +5,13 @@ Provisioning Kubernetes Clusters in vSphere | Rancher Manager - +
    Version: v2.6

    Provisioning Kubernetes Clusters in vSphere

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

    First, you will set up your vSphere cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision nodes in vSphere.

    Then you will create a vSphere cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    For details on configuring the vSphere node template, refer to the vSphere node template configuration reference.

    For details on configuring RKE Kubernetes clusters in Rancher, refer to the cluster configuration reference.

    Preparation in vSphere

    This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters.

    The node templates are documented and tested with the vSphere Web Services API version 6.5.

    Create Credentials in vSphere​

    Before proceeding to create a cluster, you must ensure that you have a vSphere user with sufficient permissions. When you set up a node template, the template will need to use these vSphere credentials.

    Refer to this how-to guide for instructions on how to create a user in vSphere with the required permissions. These steps result in a username and password that you will need to provide to Rancher, which allows Rancher to provision resources in vSphere.

    Network Permissions​

    It must be ensured that the hosts running the Rancher server are able to establish the following network connections:

    • To the vSphere API on the vCenter server (usually port 443/TCP).
    • To the Host API (port 443/TCP) on all ESXi hosts used to instantiate virtual machines for the clusters (only required when using the ISO creation method).
    • To port 22/TCP and 2376/TCP on the created VMs

    See Node Networking Requirements for a detailed list of port requirements applicable for creating nodes on an infrastructure provider.

    Valid ESXi License for vSphere API Access​

    The free ESXi license does not support API access. The vSphere servers must have a valid or evaluation ESXi license.

    VM-VM Affinity Rules for Clusters with DRS​

    If you have a cluster with DRS enabled, setting up VM-VM Affinity Rules is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate ESXi hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes.

    Creating a vSphere Cluster​

    The a vSphere cluster is created in Rancher depends on the Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click VMware vSphere.
    5. Enter your vSphere credentials. For help, refer to Account Access in the node template configuration reference.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for vSphere will allow Rancher to provision new nodes in vSphere. Node templates can be reused for other clusters.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Click Create.
    4. Click Add Template.
    5. Click vSphere.
    6. Fill out a node template for vSphere. For help filling out the form, refer to the vSphere node template configuration reference..
    7. Click Create.

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in vSphere.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click VMware vSphere.
    4. Enter a Cluster Name and use your vSphere cloud credentials. Click Continue.
    5. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. If you want to dynamically provision persistent storage or other infrastructure later, you will need to enable the vSphere cloud provider by modifying the cluster YAML file. For details, refer to this section.
    8. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to the nodes, see this section.
    9. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    • Provision Storage: For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html index 33ad8a677a4..5dd2a559851 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html @@ -5,13 +5,13 @@ Configuration for Storage Classes in Azure | Rancher Manager - +
    Version: v2.6

    Configuration for Storage Classes in Azure

    If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster.

    In order to have the Azure platform create the required storage resources, follow these steps:

    1. Configure the Azure cloud provider.

    2. Configure kubectl to connect to your cluster.

    3. Copy the ClusterRole and ClusterRoleBinding manifest for the service account:

      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: system:azure-cloud-provider
      rules:
      - apiGroups: ['']
        resources: ['secrets']
        verbs:     ['get','create']
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: system:azure-cloud-provider
      roleRef:
        kind: ClusterRole
        apiGroup: rbac.authorization.k8s.io
        name: system:azure-cloud-provider
      subjects:
      - kind: ServiceAccount
        name: persistent-volume-binder
        namespace: kube-system

    4. Create these in your cluster using one of the follow command.

      # kubectl create -f <MANIFEST>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html index 1bd55507de6..344ae78cfb5 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html @@ -5,13 +5,13 @@ Networking Requirements for Host Gateway (L2bridge) | Rancher Manager - +
    Version: v2.6

    Networking Requirements for Host Gateway (L2bridge)

    This section describes how to configure custom Windows clusters that are using Host Gateway (L2bridge) mode.

    Disabling Private IP Address Checks​

    If you are using Host Gateway (L2bridge) mode and hosting your nodes on any of the cloud services listed below, you must disable the private IP address checks for both your Linux or Windows hosts on startup. To disable this check for each node, follow the directions provided by each service below.

    ServiceDirections to disable private IP address checks
    Amazon EC2Disabling Source/Destination Checks
    Google GCEEnabling IP Forwarding for Instances (By default, a VM cannot forward a packet originated by another VM)
    Azure VMEnable or Disable IP Forwarding

    Cloud-hosted VM Routes Configuration​

    If you are using the Host Gateway (L2bridge) backend of Flannel, all containers on the same node belong to a private subnet, and traffic routes from a subnet on one node to a subnet on another node through the host network.

    • When worker nodes are provisioned on AWS, virtualization clusters, or bare metal servers, make sure they belong to the same layer 2 subnet. If the nodes don't belong to the same layer 2 subnet, host-gw networking will not work.

    • When worker nodes are provisioned on GCE or Azure, they are not on the same layer 2 subnet. Nodes on GCE and Azure belong to a routable layer 3 network. Follow the instructions below to configure GCE and Azure so that the cloud network knows how to route the host subnets on each node.

    To configure host subnet routing on GCE or Azure, first run the following command to find out the host subnets on each worker node:

    kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR

    Then follow the instructions for each cloud provider to configure routing rules for each node:

    ServiceInstructions
    Google GCEFor GCE, add a static route for each node: Adding a Static Route.
    Azure VMFor Azure, create a routing table: Custom Routes: User-defined.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html index c299522f29c..dcb0b9e7998 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html @@ -5,13 +5,13 @@ Windows and Linux Cluster Feature Parity | Rancher Manager - +
    Version: v2.6

    Windows and Linux Cluster Feature Parity

    Windows clusters do not share the same feature support as Linux clusters.

    The following chart describes the feature parity between Windows and Linux on Rancher:

    ComponentLinuxWindows
    Distributions
    RKESupportedSupported
    RKE2SupportedSupported
    K3SSupportedNot Supported
    EKSSupportedNot Supported
    GKESupportedNot Supported
    AKSSupportedNot Supported
    Rancher Components
    ServerSupportedNot Supported
    AgentSupportedSupported
    FleetSupportedSupported
    EKS OperatorSupportedNot Supported
    AKS OperatorNot SupportedNot Supported
    GKE OperatorNot SupportedNot Supported
    Alerting v1SupportedSupported
    Monitoring v1SupportedSupported
    Logging v1SupportedSupported
    Monitoring/Alerting v2SupportedSupported
    Logging v2SupportedSupported
    IstioSupportedNot Supported
    Catalog v1SupportedNot Supported
    Catalog v2SupportedNot Supported
    OPASupportedNot Supported
    LonghornSupportedNot Supported
    CIS ScansSupportedNot Supported
    Backup/Restore OperatorSupportedNot Supported
    CNI / Add-ons
    FlannelSupportedSupported
    CanalSupportedNot Supported
    CalicoSupportedSupported (RKE2 Only)
    CiliumSupportedNot Supported
    MultusSupportedNot Supported
    TraefikSupportedNot Supported
    NGINX IngressSupportedNot Supported

    For updated information on feature support, you may visit rancher/windows on GitHub.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/workload-migration-guidance.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/workload-migration-guidance.html index d2b02e9a468..81092151512 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/workload-migration-guidance.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/workload-migration-guidance.html @@ -5,13 +5,13 @@ RKE1 to RKE2 Windows Migration Guidance | Rancher Manager - +
    Version: v2.6

    RKE1 to RKE2 Windows Migration Guidance

    Caution: The contents of this document are not covered under SLA by Rancher Support. Please proceed with caution.

    This document covers how end users can migrate their Windows workloads from RKE1 to RKE2.

    RKE1 Windows Scheduling​

    RKE1 Windows workload scheduling is based on taints and tolerations.

    Every Linux node in an RKE1 Windows cluster, regardless of the role assigned to it, will have have a default taint that prevents workloads to be scheduled on it unless the workload has a toleration configured. This is a major design feature for RKE1 Windows clusters which were designed to only run Windows workloads.

    • Default RKE1 Linux node NoSchedule taint:
    apiVersion: v1
    kind: Node
    spec:
      ...
      taints:
      - effect: NoSchedule
        key: cattle.io/os
        value: linux

    • RKE1 Linux NoSchedule toleration for workloads

    The following toleration would allow an end-user workload to schedule on any Linux node of an RKE1 Windows cluster. These tolerations are used for various core Rancher services and workloads.

    apiVersion: apps/v1
    kind: Deployment
    spec:
      ...
      template:
        ...
        spec:
          tolerations:
          - effect: NoSchedule
            key: cattle.io/os
            operator: Equal
            value: linux

    • Aligning with best practices, any end-user workloads being run on Linux nodes would be scheduled on those with the worker role only:
    apiVersion: apps/v1
    kind: Deployment
    spec:
      ...
      template:
        ...
        spec:
          tolerations:
          - effect: NoSchedule
            key: cattle.io/os
            operator: Equal
            value: linux
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
              - preference:
                  matchExpressions:
                  - key: node-role.kubernetes.io/worker
                    operator: In
                    values:
                    - "true"
                weight: 100
          ...

    RKE2 Windows Scheduling​

    Based on feedback and requests for hybrid workload support, RKE2 Windows was designed to support both Linux and Windows workloads by default. RKE2 scheduling relies on node selectors by default. This is a marked change from RKE1 as taints and tolerations were not incorporated into RKE2. Node selectors were a critical part of RKE1 Windows clusters, which makes for an easy migration of your workloads.

    Example Migrations​

    RKE1 to RKE2 Windows Workload​

    • Pre-migration RKE1 Windows deployment:
    apiVersion: apps/v1
    kind: Deployment
    spec:
      ...
      template:
        ...
        spec:
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                - matchExpressions:
                  - key: kubernetes.io/os
                    operator: NotIn
                    values:
                    - linux

    • Migrated RKE2 Windows deployment using NodeAffinity:
    apiVersion: apps/v1
    kind: Deployment
    ...
    spec:
      ...
      template:
        ...
        spec:
          ...
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                nodeSelectorTerms:
                  - matchExpressions:
                      - key: kubernetes.io/os
                        operator: In
                        values:
                          - windows

    RKE1 Windows Cluster Linux-Only Deployment​

    Important: When leveraging node selectors and node affinity, note the following:

    • If both nodeSelector and nodeAffinity are specified, both must be satisfied for the Pod to be scheduled onto a node.
    • If you specify multiple matchExpressions associated with a single nodeSelectorTerms, then the Pod can be scheduled onto a node only if all the matchExpressions are satisfied.

    • Pre-migration RKE1 Windows cluster Linux-only deployment targeting RKE1 Linux worker nodes:
    apiVersion: apps/v1
    kind: Deployment
    spec:
      ...
      template:
        ...
        spec:
          tolerations:
          - effect: NoSchedule
            key: cattle.io/os
            operator: Equal
            value: linux
          affinity:
            nodeAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
              - weight: 100
                preference:
                  matchExpressions:
                  - key: node-role.kubernetes.io/worker
                    operator: In
                    values:
                    - "true"


    • Migrated RKE2 hybrid cluster Linux-only deployment targeting RKE2 Linux worker nodes using node selectors:
    apiVersion: apps/v1
    kind: Deployment
    spec:
      ...
      template:
        ...
        spec:
          nodeSelector:
            kubernetes.io/os: "linux"
            node-role.kubernetes.io/worker: "true"

    • Migrated RKE2 hybrid cluster Linux-only deployment targeting RKE2 Linux worker nodes using node affinity:

      apiVersion: apps/v1
      kind: Deployment
      spec:
       ...
       template:
         ...
         spec:
            affinity:
             nodeAffinity:
               requiredDuringSchedulingIgnoredDuringExecution:
               - weight: 100
                 preference:
                   matchExpressions:
                   - key: node-role.kubernetes.io/worker
                     operator: In
                     values:
                     - "true"
                 nodeSelectorTerms:
                   - matchExpressions:
                       - key: kubernetes.io/os
                         operator: In
                         values:
                           - linux

    RKE1 Windows-Supported Windows Server Versions​

    Long-Term Servicing Channel (LTSC)​

    • Windows Server 2019 LTSC ✅ Will reach Mainstream EOL on Jan 9, 2024 and Extended EOL on Jan 9, 2029

    Semi-Annual Channel (SAC)​

    • Windows Server 20H2 SAC ❌ EOL Reached on Aug 9, 2022
    • Windows Server 2004 SAC ❌ EOL Reached on Dec 14, 2021
    • Windows Server 1909 SAC ❌ EOL Reached on May 11, 2021
    • Windows Server 1903 SAC ❌ EOL Reached on Dec 8, 2020
    • Windows Server 1809 SAC ❌ EOL Reached on Nov 10, 2020

    RKE2 Windows-Supported Windows Server Versions​

    Long-Term Servicing Channel in RKE2​

    • Windows Server 2019 LTSC ✅ Will reach Mainstream EOL on Jan 9, 2024 and Extended EOL on Jan 9, 2029
    • Windows Server 2022 LTSC ✅ Will reach Mainstream EOL on Oct 13, 2026 and Extended EOL on Oct 13, 2031

    Note: SAC is not supported in RKE2.

    For more information, please see the following references:

    Kubernetes Version Support​

    Note: All versions listed below are SLA Supported per the Rancher v2.6.7 Support Matrix. Any version not listed should be assumed as being EOL and not supported under SLA by SUSE.

    Rancher 2.5 vs. Rancher 2.6 Support Matrix for Windows Clusters​

    RKE1 vs. RKE2 Windows cluster-supported Kubernetes versions:

    Kubernetes VersionsRKE1RKE2
    1.18✓
    1.19✓
    1.20✓
    1.21✓
    1.22✓✓
    1.23✓
    1.24✓
    1.25+✓

    Rancher 2.5 vs. Rancher 2.6 Supported Kubernetes Versions for Provisioning RKE1 and RKE2 Windows Clusters​

    Rancher VersionsKubernetes VersionsRKE1RKE2
    2.5 - RKE1 Provisioning1.18 1.19 1.20✓
    2.6 - RKE1 Provisioning1.18 1.19 1.20 1.21 1.22✓
    2.6 - RKE2 Provisioning1.22 1.23 1.24 1.25+✓

    Guiding Migrations of Workloads to RKE2 Windows​

    Referencing the tables in Rancher 2.5 vs. Rancher 2.6 Support Matrix for Windows Clusters and Rancher 2.5 vs. Rancher 2.6 Supported Kubernetes Versions for Provisioning RKE1 and RKE2 Windows Clusters, you will find the overlap in Kubernetes versions between RKE1 and RKE2 occurs in 1.22. This will be the base version required to migrate RKE1 Windows workloads when following the Rancher recommended approach.

    In-Place Upgrade of Rancher 2.5​

    1. Upgrade the Rancher version to v2.6.5+.
    2. Upgrade the RKE1 Windows downstream cluster(s) to RKE1 v1.22 using the latest available patch version.
    3. Provision a new RKE2 Windows downstream cluster using RKE2 v1.22 using the matching patch version that the RKE1 Windows cluster is at.
    4. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters.
    5. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2.
    6. After successful validation tests have occurred, you can opt to upgrade your RKE2 1.22.x cluster to a new minor version such as 1.23 or 1.24.

    Migrating Windows Workloads to a New Rancher Environment​

    Important: To perform either of the following options requires Rancher v2.6.5 or above.

    When using matching Kubernetes patch versions for RKE1 and RKE2:

    1. Provision a new RKE2 Windows downstream cluster using RKE2 v1.22 using the matching patch version that the RKE1 Windows cluster is at.
    2. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters.
    3. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2.
    4. After successful validation tests have occurred, you can opt to upgrade your RKE2 1.22.x cluster to a new minor version such as 1.23 or 1.24.

    When using a newer Kubernetes patch version for RKE2:

    1. Provision a new RKE2 Windows downstream cluster using RKE2 v1.23 or v1.24.
    2. Begin the migration of the Windows workloads from RKE1 to RKE2 clusters.
    3. Perform validation tests to ensure that there has been no functionality loss or change when migrating your application from RKE1 to RKE2.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html index 4475785b6e6..ba110b32ae3 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html @@ -5,13 +5,13 @@ Node Requirements for Rancher Managed Clusters | Rancher Manager - +
    Version: v2.6

    Node Requirements for Rancher Managed Clusters

    This page describes the requirements for the Rancher managed Kubernetes clusters where your apps and services will be installed. These downstream clusters should be separate from the three-node cluster running Rancher.

    note

    If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the installation section.

    Operating Systems and Container Runtime Requirements​

    Rancher should work with any modern Linux distribution and any modern Docker version. Linux is required for the etcd and controlplane nodes of all downstream clusters. Worker nodes may run Linux or Windows Server.

    For details on which OS and Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    All supported operating systems are 64-bit x86.

    If you plan to use ARM64, see Running on ARM64 (Experimental).

    For information on how to install Docker, refer to the official Docker documentation.

    Oracle Linux and RHEL Derived Linux Nodes​

    Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.

    note

    In RHEL 8.4, two extra services are included on the NetworkManager: nm-cloud-setup.service and nm-cloud-setup.timer. These services add a routing table that interferes with the CNI plugin's configuration. If these services are enabled, you must disable them using the command below, and then reboot the node to restore connectivity:

    systemctl disable nm-cloud-setup.service nm-cloud-setup.timer
    reboot

    SUSE Linux Nodes​

    SUSE Linux may have a firewall that blocks all ports by default. In that situation, follow these steps to open the ports needed for adding a host to a custom cluster.

    Flatcar Container Linux Nodes​

    When Launching Kubernetes with Rancher using Flatcar Container Linux nodes, it is required to use the following configuration in the Cluster Config File

    rancher_kubernetes_engine_config:
      network:
        plugin: canal
        options:
          canal_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds
          flannel_backend_type: vxlan

      services:
        kube-controller:
          extra_args:
            flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/

    It is also required to enable the Docker service, you can enable the Docker service using the following command:

    systemctl enable docker.service

    The Docker service is enabled automatically when using Node Drivers.

    Windows Nodes​

    Nodes with Windows Server must run Docker Enterprise Edition.

    Windows nodes can be used for worker nodes only. See Configuring Custom Clusters for Windows

    Hardware Requirements​

    The hardware requirements for nodes with the worker role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory.

    Regarding CPU and memory, it is recommended that the different planes of Kubernetes clusters (etcd, controlplane, and workers) should be hosted on different nodes so that they can scale separately from each other.

    For hardware recommendations for large Kubernetes clusters, refer to the official Kubernetes documentation on building large clusters.

    For hardware recommendations for etcd clusters in production, refer to the official etcd documentation.

    Networking Requirements​

    For a production cluster, we recommend that you restrict traffic by opening only the ports defined in the port requirements below.

    The ports required to be open are different depending on how the user cluster is launched. Each of the sections below list the ports that need to be opened for different cluster creation options.

    For a breakdown of the port requirements for etcd nodes, controlplane nodes, and worker nodes in a Kubernetes cluster, refer to the port requirements for the Rancher Kubernetes Engine.

    Details on which ports are used in each situation are found under Downstream Cluster Port Requirements.

    Optional: Security Considerations​

    If you want to provision a Kubernetes cluster that is compliant with the CIS (Center for Internet Security) Kubernetes Benchmark, we recommend to following our hardening guide to configure your nodes before installing Kubernetes.

    For more information on the hardening guide and details on which version of the guide corresponds to your Rancher and Kubernetes versions, refer to the security section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html index d19a18a5034..4a0eab07cf7 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html @@ -5,7 +5,7 @@ Registering Existing Clusters | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.6

    Registering Existing Clusters

    The cluster registration feature replaced the feature to import clusters.

    The control that Rancher has to manage a registered cluster depends on the type of cluster. For details, see Management Capabilities for Registered Clusters.

    Prerequisites​

    Kubernetes Node Roles​

    Registered RKE Kubernetes clusters must have all three node roles - etcd, controlplane and worker. A cluster with only controlplane components cannot be registered in Rancher.

    For more information on RKE node roles, see the best practices.

    Permissions​

    If your existing Kubernetes cluster already has a cluster-admin role defined, you must have this cluster-admin privilege to register the cluster in Rancher.

    In order to apply the privilege, you need to run:

    kubectl create clusterrolebinding cluster-admin-binding \
      --clusterrole cluster-admin \
      --user [USER_ACCOUNT]

    before running the kubectl command to register the cluster.

    By default, GKE users are not given this privilege, so you will need to run the command before registering GKE clusters. To learn more about role-based access control for GKE, please click here.

    If you are registering a K3s cluster, make sure the cluster.yml is readable. It is protected by default. For details, refer to Configuring a K3s cluster to enable importation to Rancher.

    EKS Clusters​

    EKS clusters must have at least one managed node group to be imported into Rancher or provisioned from Rancher successfully.

    Registering a Cluster​

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, Import Existing.
    3. Choose the type of cluster.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. If you are importing a generic Kubernetes cluster in Rancher, perform the following steps for setup:
      a. Click Agent Environment Variables under Cluster Options to set environment variables for rancher cluster agent. The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables can be set using agent environment variables.
      b. Enable Project Network Isolation to ensure the cluster supports Kubernetes NetworkPolicy resources. Users can select the Project Network Isolation option under the Advanced Options dropdown to do so.
    6. Click Create.
    7. The prerequisite for cluster-admin privileges is shown (see Prerequisites above), including an example command to fulfil the prerequisite.
    8. Copy the kubectl command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run kubectl get nodes to verify before running the command shown in Rancher.
    9. If you are using self-signed certificates, you will receive the message certificate signed by unknown authority. To work around this validation, copy the command starting with curl displayed in Rancher to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import.
    10. When you finish running the command(s) on your node, click Done.

    Result:

    • Your cluster is registered and assigned a state of Pending. Rancher is deploying resources to manage your cluster.
    • You can access your cluster after its state is updated to Active.
    • Active clusters are assigned two Projects: Default (containing the namespace default) and System (containing the namespaces cattle-system, ingress-nginx, kube-public and kube-system, if present).
    note

    You can not re-register a cluster that is currently active in a Rancher setup.

    Configuring a K3s Cluster to Enable Registration in Rancher​

    The K3s server needs to be configured to allow writing to the kubeconfig file.

    This can be accomplished by passing --write-kubeconfig-mode 644 as a flag during installation:

    $ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

    The option can also be specified using the environment variable K3S_KUBECONFIG_MODE:

    $ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -

    Configuring an Imported EKS Cluster with Terraform​

    You should define only the minimum fields that Rancher requires when importing an EKS cluster with Terraform. This is important as Rancher will overwrite what was in the EKS cluster with any config that the user has provided.

    caution

    Even a small difference between the current EKS cluster and a user-provided config could have unexpected results.

    The minimum config fields required by Rancher to import EKS clusters with Terraform using eks_config_v2 are as follows:

    • cloud_credential_id
    • name
    • region
    • imported (this field should always be set to true for imported clusters)

    Example YAML configuration for imported EKS clusters:

    resource "rancher2_cluster" "my-eks-to-import" {
      name        = "my-eks-to-import"
      description = "Terraform EKS Cluster"
      eks_config_v2 {
        cloud_credential_id = rancher2_cloud_credential.aws.id
        name                = var.aws_eks_name
        region              = var.aws_region
        imported            = true
      }
    }

    Management Capabilities for Registered Clusters​

    The control that Rancher has to manage a registered cluster depends on the type of cluster.

    Features for All Registered Clusters​

    After registering a cluster, the cluster owner can:

    Additional Features for Registered K3s Clusters​

    K3s is a lightweight, fully compliant Kubernetes distribution.

    When a K3s cluster is registered in Rancher, Rancher will recognize it as K3s. The Rancher UI will expose the features for all registered clusters, in addition to the following features for editing and upgrading the cluster:

    • The ability to upgrade the K3s version
    • The ability to configure the maximum number of nodes that will be upgraded concurrently
    • The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster

    Additional Features for Registered EKS and GKE Clusters​

    Registering an Amazon EKS cluster or GKE cluster allows Rancher to treat it as though it were created in Rancher.

    Amazon EKS clusters and GKE clusters can now be registered in Rancher. For the most part, these registered clusters are treated the same way as clusters created in the Rancher UI, except for deletion.

    When you delete an EKS cluster or GKE cluster that was created in Rancher, the cluster is destroyed. When you delete a cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.

    The capabilities for registered clusters are listed in the table on this page.

    Configuring K3s Cluster Upgrades​

    tip

    It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider.

    The concurrency is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the concurrency, the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed.

    • Controlplane concurrency: The maximum number of server nodes to upgrade at a single time; also the maximum unavailable server nodes
    • Worker concurrency: The maximum number worker nodes to upgrade at the same time; also the maximum unavailable worker nodes

    In the K3s documentation, controlplane nodes are called server nodes. These nodes run the Kubernetes master, which maintains the desired state of the cluster. In K3s, these controlplane nodes have the capability to have workloads scheduled to them by default.

    Also in the K3s documentation, nodes with the worker role are called agent nodes. Any workloads or pods that are deployed in the cluster can be scheduled to these nodes by default.

    Debug Logging and Troubleshooting for Registered K3s Clusters​

    Nodes are upgraded by the system upgrade controller running in the downstream cluster. Based on the cluster configuration, Rancher deploys two plans to upgrade K3s nodes: one for controlplane nodes and one for workers. The system upgrade controller follows the plans and upgrades the nodes.

    To enable debug logging on the system upgrade controller deployment, edit the configmap to set the debug environment variable to true. Then restart the system-upgrade-controller pod.

    Logs created by the system-upgrade-controller can be viewed by running this command:

    kubectl logs -n cattle-system system-upgrade-controller

    The current status of the plans can be viewed with this command:

    kubectl get plans -A -o yaml

    If the cluster becomes stuck in upgrading, restart the system-upgrade-controller.

    To prevent issues when upgrading, the Kubernetes upgrade best practices should be followed.

    Authorized Cluster Endpoint Support for RKE2 and K3s Clusters​

    Available as of v2.6.3

    Authorized Cluster Endpoint (ACE) support has been added for registered RKE2 and K3s clusters. This support includes manual steps you will perform on the downstream cluster to enable the ACE. For additional information on the authorized cluster endpoint, click here.

    Notes:

    • These steps only need to be performed on the control plane nodes of the downstream cluster. You must configure each control plane node individually.

    • The following steps will work on both RKE2 and K3s clusters registered in v2.6.x as well as those registered (or imported) from a previous version of Rancher with an upgrade to v2.6.x.

    • These steps will alter the configuration of the downstream RKE2 and K3s clusters and deploy the kube-api-authn-webhook. If a future implementation of the ACE requires an update to the kube-api-authn-webhook, then this would also have to be done manually. For more information on this webhook, click here.

    Manual steps to be taken on the control plane of each downstream cluster to enable ACE:​

    1. Create a file at /var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml with the following contents:

      apiVersion: v1
      kind: Config
      clusters:
      - name: Default
        cluster:
          insecure-skip-tls-verify: true
          server: http://127.0.0.1:6440/v1/authenticate
      users:
      - name: Default
        user:
          insecure-skip-tls-verify: true
      current-context: webhook
      contexts:
      - name: webhook
        context:
          user: Default
          cluster: Default

    2. Add the following to the config file (or create one if it doesn’t exist); note that the default location is /etc/rancher/{rke2,k3s}/config.yaml:

      kube-apiserver-arg:
          - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml

    3. Run the following commands:

      sudo systemctl stop {rke2,k3s}-server
      sudo systemctl start {rke2,k3s}-server

    4. Finally, you must go back to the Rancher UI and edit the imported cluster there to complete the ACE enablement. Click on ⋮ > Edit Config, then click the Networking tab under Cluster Configuration. Finally, click the Enabled button for Authorized Endpoint. Once the ACE is enabled, you then have the option of entering a fully qualified domain name (FQDN) and certificate information.

    note

    The FQDN field is optional, and if one is entered, it should point to the downstream cluster. Certificate information is only needed if there is a load balancer in front of the downstream cluster that is using an untrusted certificate. If you have a valid certificate, then nothing needs to be added to the CA Certificates field.

    Annotating Registered Clusters​

    For all types of registered Kubernetes clusters except for K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured.

    Therefore, when Rancher registers a cluster, it assumes that several capabilities are disabled by default. Rancher assumes this in order to avoid exposing UI options to the user even when the capabilities are not enabled in the registered cluster.

    However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster.

    By annotating a registered cluster, it is possible to indicate to Rancher that a cluster was given a pod security policy, or another capability, outside of Rancher.

    This example annotation indicates that a pod security policy is enabled:

    "capabilities.cattle.io/pspEnabled": "true"

    The following annotation indicates Ingress capabilities. Note that that the values of non-primitive objects need to be JSON encoded, with quotations escaped.

    "capabilities.cattle.io/ingressCapabilities": "[
      {
        "customDefaultBackend":true,
        "ingressProvider":"asdf"
      }
    ]"

    These capabilities can be annotated for the cluster:

    • ingressCapabilities
    • loadBalancerCapabilities
    • nodePoolScalingSupported
    • nodePortRange
    • pspEnabled
    • taintSupport

    All the capabilities and their type definitions can be viewed in the Rancher API view, at [Rancher Server URL]/v3/schemas/capabilities.

    To annotate a registered cluster,

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, go to the custom cluster you want to annotate and click ⋮ > Edit Config.
    3. Expand the Labels & Annotations section.
    4. Click Add Annotation.
    5. Add an annotation to the cluster with the format capabilities/<capability>: <value> where value is the cluster capability that will be overridden by the annotation. In this scenario, Rancher is not aware of any capabilities of the cluster until you add the annotation.
    6. Click Save.

    Result: The annotation does not give the capabilities to the cluster, but it does indicate to Rancher that the cluster has those capabilities.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html index 062a9de5f32..d09297c0e4e 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html @@ -5,13 +5,13 @@ Creating an AKS Cluster | Rancher Manager - +
    Version: v2.6

    Creating an AKS Cluster

    You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS).

    Prerequisites in Microsoft Azure​

    caution

    Deploying to AKS will incur charges.

    To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the AKS documentation.

    Before creating the service principal, you need to obtain the following information from the Microsoft Azure Portal:

    • Subscription ID
    • Client ID
    • Client secret

    The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal.

    Setting Up the Service Principal with the Azure Command Line Tool​

    You can create the service principal by running this command:

    az ad sp create-for-rbac --skip-assignment

    The result should show information about the new service principal:

    {
      "appId": "xxxx--xxx",
      "displayName": "<SERVICE-PRINCIPAL-NAME>",
      "name": "http://<SERVICE-PRINCIPAL-NAME>",
      "password": "<SECRET>",
      "tenant": "<TENANT NAME>"
    }

    You also need to add roles to the service principal so that it has privileges for communication with the AKS API. It also needs access to create and list virtual networks.

    Below is an example command for assigning the Contributor role to a service principal. Contributors can manage anything on AKS but cannot give access to others:

    az role assignment create \
      --assignee $appId \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    You can also create the service principal and give it Contributor privileges by combining the two commands into one. In this command, the scope needs to provide a full path to an Azure resource:

    az ad sp create-for-rbac \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    Setting Up the Service Principal from the Azure Portal​

    You can also follow these instructions to set up a service principal and give it role-based access from the Azure Portal.

    1. Go to the Microsoft Azure Portal home page.

    2. Click Azure Active Directory.

    3. Click App registrations.

    4. Click New registration.

    5. Enter a name. This will be the name of your service principal.

    6. Optional: Choose which accounts can use the service principal.

    7. Click Register.

    8. You should now see the name of your service principal under Azure Active Directory > App registrations.

    9. Click the name of your service principal. Take note of the application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click Certificates & secrets.

    10. Click New client secret.

    11. Enter a short description, pick an expiration time, and click Add. Take note of the client secret so that you can use it when provisioning the AKS cluster.

    Result: You have created a service principal and you should be able to see it listed in the Azure Active Directory section under App registrations. You still need to give the service principal access to AKS.

    To give role-based access to your service principal,

    1. Click All Services in the left navigation bar. Then click Subscriptions.
    2. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster.
    3. Click Access Control (IAM).
    4. In the Add role assignment section, click Add.
    5. In the Role field, select a role that will have access to AKS. For example, you can use the Contributor role, which has permission to manage everything except for giving access to other users.
    6. In the Assign access to field, select Azure AD user, group, or service principal.
    7. In the Select field, select the name of your service principal and click Save.

    Result: Your service principal now has access to AKS.

    1. Create the AKS Cloud Credentials​

    1. In the Rancher UI, click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click Azure.
    5. Fill out the form. For help with filling out the form, see the configuration reference.
    6. Click Create.

    2. Create the AKS Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. Click ☰ > Cluster Management.
    2. In the Clusters section, click Create.
    3. Click Azure AKS.
    4. Fill out the form. For help with filling out the form, see the configuration reference.
    5. Click Create.

    Result: Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Role-based Access Control​

    When provisioning an AKS cluster in the Rancher UI, RBAC is not configurable because it is required to be enabled.

    RBAC is required for AKS clusters that are registered or imported into Rancher.

    AKS Cluster Configuration Reference​

    For more information about how to configure AKS clusters from the Rancher UI, see the configuration reference.

    Private Clusters​

    Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint.

    Rancher can connect to a private AKS cluster in one of two ways.

    The first way to ensure that Rancher is running on the same NAT as the AKS nodes.

    The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled.

    note

    Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the Cluster To register dropdown list. This outcome will be based on region.

    For more information about connecting to an AKS private cluster, see the AKS documentation.

    Syncing​

    The AKS provisioner can synchronize the state of an AKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

    For information on configuring the refresh interval, see this section.

    Programmatically Creating AKS Clusters​

    The most common way to programmatically deploy AKS clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html index 48b4137817b..9441385d15a 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html @@ -5,13 +5,13 @@ Creating an Aliyun ACK Cluster | Rancher Manager - +
    Version: v2.6

    Creating an Aliyun ACK Cluster

    You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the cluster driver for ACK, but by default, this cluster driver is inactive. In order to launch ACK clusters, you will need to enable the ACK cluster driver. After enabling the cluster driver, you can start provisioning ACK clusters.

    Prerequisites Outside of Rancher​

    caution

    Deploying to ACK will incur charges.

    1. In Aliyun, activate the following services in their respective consoles.

    2. Make sure that the account you will be using to create the ACK cluster has the appropriate permissions. Referring to the official Alibaba Cloud documentation about Role authorization and Use the Container Service console as a RAM user for details.

    3. In Alibaba Cloud, create an access key.

    4. In Alibaba Cloud, create an SSH key pair. This key is used to access nodes in the Kubernetes cluster.

    Prerequisite in Rancher​

    You will need to enable the Alibaba ACK cluster driver:

    1. Click ☰ > Cluster Management.
    2. Click Drivers.
    3. In the Cluster Drivers tab, go to the Alibaba ACK cluster driver and click ⋮ > Activate.

    When the cluster driver is finished downloading, you will be able to create Alibaba ACK clusters in Rancher.

    Create an ACK Cluster​

    1. Click ☰ > Cluster Management.
    2. From the Clusters page, click Create.
    3. Choose Alibaba ACK.
    4. Enter a Cluster Name.
    5. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Configure Account Access for the ACK cluster. Choose the geographical region in which to build your cluster, and input the access key that was created as part of the prerequisite steps.
    7. Click Next: Configure Cluster, then choose cluster type, the version of Kubernetes and the availability zone.
    8. If you choose Kubernetes as the cluster type, Click Next: Configure Master Nodes, then complete the Master Nodes form.
    9. Click Next: Configure Worker Nodes, then complete the Worker Nodes form.
    10. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html index 39e2208ede1..e20367a5e2b 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html @@ -5,13 +5,13 @@ Managing GKE Clusters | Rancher Manager - +
    Version: v2.6

    Managing GKE Clusters

    Prerequisites​

    Some setup in Google Kubernetes Engine is required.

    Service Account Token​

    Create a service account using Google Kubernetes Engine. GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication.

    The service account requires the following roles:

    • Compute Viewer: roles/compute.viewer
    • Project Viewer: roles/viewer
    • Kubernetes Engine Admin: roles/container.admin
    • Service Account User: roles/iam.serviceAccountUser

    Google Documentation: Creating and Enabling Service Accounts

    For help obtaining a private key for your service account, refer to the Google cloud documentation here. You will need to save the key in JSON format.

    Google Project ID​

    Your cluster will need to be part of a Google Project.

    To create a new project, refer to the Google cloud documentation here.

    To get the project ID of an existing project, refer to the Google cloud documentation here.

    Provisioning a GKE Cluster​

    caution

    Deploying to GKE will incur charges.

    1. Create a Cloud Credential​

    1. Click ☰ > Cluster Management.
    2. In the left navigation bar, click Cloud Credentials.
    3. Click Create.
    4. Enter a name for your Google cloud credentials.
    5. In the Service Account text box, paste your service account private key JSON, or upload the JSON file.
    6. Click Create.

    Result: You have created credentials that Rancher will use to provision the new GKE cluster.

    2. Create the GKE Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click Google GKE.
    4. Enter a Cluster Name.
    5. Optional: Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Optional: Add Kubernetes labels or annotations to the cluster.
    7. Enter your Google project ID and your Google cloud credentials.
    8. Fill out the rest of the form. For help, refer to the GKE cluster configuration reference.
    9. Click Create.

    Result: You have successfully deployed a GKE cluster.

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Private Clusters​

    Private GKE clusters are supported. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see this section.

    Configuration Reference​

    For details on configuring GKE clusters in Rancher, see this page.

    Updating Kubernetes Version​

    The Kubernetes version of a cluster can be upgraded to any version available in the region or zone fo the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently.

    note

    GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the Google documentation. After this, the Kubernetes version can be updated to 1.19+ via Rancher.

    Syncing​

    The GKE provisioner can synchronize the state of a GKE cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

    For information on configuring the refresh interval, see this section.

    Programmatically Creating GKE Clusters​

    The most common way to programmatically deploy GKE clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html index 63a0168ced6..b3444615b61 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html @@ -5,13 +5,13 @@ Creating a Huawei CCE Cluster | Rancher Manager - +
    Version: v2.6

    Creating a Huawei CCE Cluster

    You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the cluster driver for CCE, but by default, this cluster driver is inactive. In order to launch CCE clusters, you will need to enable the CCE cluster driver. After enabling the cluster driver, you can start provisioning CCE clusters.

    Prerequisites in Huawei​

    caution

    Deploying to CCE will incur charges.

    1. Find your project ID in Huawei CCE portal. See the CCE documentation on how to manage your projects.

    2. Create an Access Key ID and Secret Access Key.

    Prerequisite in Rancher​

    You will need to enable the Huawei CCE cluster driver:

    1. Click ☰ > Cluster Management.
    2. Click Drivers.
    3. In the Cluster Drivers tab, go to the Huawei CCE cluster driver and click ⋮ > Activate.

    When the cluster driver is finished downloading, you will be able to create Huawei CCE clusters in Rancher.

    Limitations​

    Huawei CCE service doesn't support the ability to create clusters with public access through their API. You are required to run Rancher in the same VPC as the CCE clusters that you want to provision.

    Create the CCE Cluster​

    1. From the Clusters page, click Create.
    2. Click Huawei CCE.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Enter Project Id, Access Key ID as Access Key and Secret Access Key Secret Key. Then Click Next: Configure cluster. Fill in the cluster configuration. For help filling out the form, refer to Huawei CCE Configuration.
    6. Fill the following node configuration of the cluster. For help filling out the form, refer to Node Configuration.
    7. Click Create to create the CCE cluster.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Huawei CCE Configuration​

    SettingsDescription
    Cluster TypeWhich type or node you want to include into the cluster, VirtualMachine or BareMetal.
    DescriptionThe description of the cluster.
    Master VersionThe Kubernetes version.
    Management Scale CountThe max node count of the cluster. The options are 50, 200 and 1000. The larger of the scale count, the more the cost.
    High AvailabilityEnable master node high availability. The cluster with high availability enabled will have more cost.
    Container Network ModeThe network mode used in the cluster. overlay_l2 and vpc-router is supported in VirtualMachine type and underlay_ipvlan is supported in BareMetal type
    Container Network CIDRNetwork CIDR for the cluster.
    VPC NameThe VPC name which the cluster is going to deploy into. Rancher will create one if it is blank.
    Subnet NameThe Subnet name which the cluster is going to deploy into. Rancher will create one if it is blank.
    External ServerThis option is reserved for the future we can enable CCE cluster public access via API. For now, it is always disabled.
    Cluster LabelThe labels for the cluster.
    Highway SubnetThis option is only supported in BareMetal type. It requires you to select a VPC with high network speed for the bare metal machines.
    note

    If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure.

    Node Configuration​

    SettingsDescription
    ZoneThe available zone at where the node(s) of the cluster is deployed.
    Billing ModeThe bill mode for the cluster node(s). In VirtualMachine type, only Pay-per-use is supported. in BareMetal, you can choose Pay-per-use or Yearly/Monthly.
    Validity PeriodThis option only shows in Yearly/Monthly bill mode. It means how long you want to pay for the cluster node(s).
    Auto RenewThis option only shows in Yearly/Monthly bill mode. It means that the cluster node(s) will renew the Yearly/Monthly payment automatically or not.
    Data Volume TypeData volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Data Volume SizeData volume size for the cluster node(s)
    Root Volume TypeRoot volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Root Volume SizeRoot volume size for the cluster node(s)
    Node FlavorThe node flavor of the cluster node(s). The flavor list in Rancher UI is fetched from Huawei Cloud. It includes all the supported node flavors.
    Node CountThe node count of the cluster
    Node Operating SystemThe operating system for the cluster node(s). Only EulerOS 2.2 and CentOS 7.4 are supported right now.
    SSH Key NameThe ssh key for the cluster node(s)
    EIPThe public IP options for the cluster node(s). Disabled means that the cluster node(s) are not going to bind a public IP. Create EIP means that the cluster node(s) will bind one or many newly created Eips after provisioned and more options will be shown in the UI to set the to-create EIP parameters. And Select Existed EIP means that the node(s) will bind to the EIPs you select.
    EIP CountThis option will only be shown when Create EIP is selected. It means how many EIPs you want to create for the node(s).
    EIP TypeThis option will only be shown when Create EIP is selected. The options are 5_bgp and 5_sbgp.
    EIP Share TypeThis option will only be shown when Create EIP is selected. The only option is PER.
    EIP Charge ModeThis option will only be shown when Create EIP is selected. The options are pay by BandWidth and pay by Traffic.
    EIP Bandwidth SizeThis option will only be shown when Create EIP is selected. The BandWidth of the EIPs.
    Authentication ModeIt means enabling RBAC or also enabling Authenticating Proxy. If you select Authenticating Proxy, the certificate which is used for authenticating proxy will be also required.
    Node LabelThe labels for the cluster node(s). Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html index 9311aed4eba..7d7ef8180f0 100644 --- a/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html +++ b/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html @@ -5,13 +5,13 @@ Creating a Tencent TKE Cluster | Rancher Manager - +
    Version: v2.6

    Creating a Tencent TKE Cluster

    You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the cluster driver for TKE, but by default, this cluster driver is inactive. In order to launch TKE clusters, you will need to enable the TKE cluster driver. After enabling the cluster driver, you can start provisioning TKE clusters.

    Prerequisites in Tencent​

    caution

    Deploying to TKE will incur charges.

    1. Make sure that the account you will be using to create the TKE cluster has the appropriate permissions by referring to the Cloud Access Management documentation for details.

    2. Create a Cloud API Secret ID and Secret Key.

    3. Create a Private Network and Subnet in the region that you want to deploy your Kubernetes cluster.

    4. Create a SSH key pair. This key is used to access the nodes in the Kubernetes cluster.

    Prerequisite in Rancher​

    You will need to enable the Tencent TKE cluster driver:

    1. Click ☰ > Cluster Management.
    2. Click Drivers.
    3. In the Cluster Drivers tab, go to the Tencent TKE cluster driver and click ⋮ > Activate.

    When the cluster driver is finished downloading, you will be able to create Tencent TKE clusters in Rancher.

    Create a TKE Cluster​

    1. From the Clusters page, click Create.

    2. Choose Tencent TKE.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Configure Account Access for the TKE cluster. Complete each drop-down and field using the information obtained in Prerequisites.

      OptionDescription
      RegionFrom the drop-down chooses the geographical region in which to build your cluster.
      Secret IDEnter the Secret ID that you obtained from the Tencent Cloud Console.
      Secret KeyEnter the Secret key that you obtained from Tencent Cloud Console.

    6. Click Next: Configure Cluster to set your TKE cluster configurations.

      OptionDescription
      Kubernetes VersionThe TKE only supports Kubernetes version 1.10.5 now.
      Node CountEnter the amount of worker node you want to purchase for your Kubernetes cluster, up to 100.
      VPCSelect the VPC name that you have created in the Tencent Cloud Console.
      Container Network CIDREnter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16.
      note

      If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that, cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    7. Click Next: Select Instance Type to choose the instance type that will use for your TKE cluster.

      OptionDescription
      Availability ZoneChoose the availability zone of the VPC region.
      SubnetSelect the Subnet that you have created within the VPC, and add a new one if you don't have it in the chosen availability zone.
      Instance TypeFrom the drop-down chooses the VM instance type that you want to use for the TKE cluster, default to S2.MEDIUM4 (CPU 2 Memory 4 GiB).

    8. Click Next: Configure Instance to configure the VM instance that will use for your TKE cluster.

      OptionDescription
      Operating SystemThe name of the operating system, currently supports Centos7.2x86_64 or ubuntu16.04.1 LTSx86_64
      Security GroupSecurity group ID, default does not bind any security groups.
      Root Disk TypeSystem disk type. System disk type restrictions are detailed in the CVM instance configuration.
      Root Disk SizeSystem disk size. Linux system adjustment range is 20 - 50G, step size is 1.
      Data Disk TypeData disk type, default value to the SSD cloud drive
      Data Disk SizeData disk size (GB), the step size is 10
      Band Width TypeType of bandwidth, PayByTraffic or PayByHour
      Band WidthPublic network bandwidth (Mbps)
      Key PairKey id, after associating the key can be used to logging to the VM node

    9. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html index 02018a654d2..bf69219f5be 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html @@ -5,13 +5,13 @@ ConfigMaps | Rancher Manager - +
    Version: v2.6

    ConfigMaps

    While most types of Kubernetes secrets store sensitive information, ConfigMaps store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect).

    ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster that has the workload that should reference a ConfigMap and click Explore.

    3. In the left navigation bar, click More Resources > Core > ConfigMaps.

    4. Click Create.

    5. Enter a Name for the Config Map.

      note

      Kubernetes classifies ConfigMaps as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace.

    6. Select the Namespace you want to add Config Map to.

    7. On the Data tab, add a key-value pair to your ConfigMap. Add as many values as you need. You can add multiple key value pairs to the ConfigMap by copying and pasting. Alternatively, use Read from File to add the data. Note: If you need to store sensitive data, use a secret, not a ConfigMap.

    8. Click Create.

    Result: Your ConfigMap is added to the namespace. You can view it in the Rancher UI from the Resources > Config Maps view.

    What's Next?​

    Now that you have a ConfigMap added to a namespace, you can add it to a workload that you deploy from the namespace of origin. You can use the ConfigMap to specify information for you application to consume, such as:

    • Application environment variables.
    • Specifying parameters for a Volume mounted to the workload.

    For more information on adding ConfigMaps to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html index 961b82eadfa..69038a1e062 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html @@ -5,14 +5,14 @@ Services | Rancher Manager - +
    Version: v2.6

    Services

    Pod configuration is managed by Deployments, StatefulSets and Daemonsets, whereas services direct traffic to pods using selectors.

    For every workload (with at least one port configured) created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention: <workload>.<namespace>.svc.cluster.local.

    You can create additional services so that a given namespace resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to add a service and click Explore.
    3. Click Service Discovery > Services.
    4. Click Create.
    5. Choose the type of service you want to create.
    6. Select a Namespace from the drop-down list.
    7. Enter a Name for the service. This name is used for DNS resolution.
    8. Fill out the rest of the form. For help, refer to the upstream Kubernetes documentation about services.
    9. Click Create.

    Result: A new service is created.

    • You can view the record by from the project's Service Discovery tab.
    • When you visit the new DNS name for the new record that you created (<recordname>.<namespace>.svc.cluster.local), it resolves the chosen namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html index fa579b196ed..e3fce924514 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html @@ -5,13 +5,13 @@ Encrypting HTTP Communication | Rancher Manager - +
    Version: v2.6

    Encrypting HTTP Communication

    When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by adding the certificate to the ingress deployment.

    Prerequisite:

    You must have a TLS private key and certificate available to upload.

    1. Create a Secret​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to deploy your ingress and click More Resources > Core > Secrets.
    3. Click Create.
    4. Click TLS Certificate.
    5. Enter a name for the secret. Note: Your secret must have a unique name among the other certificates, registries, and secrets within your project/workspace.
    6. In the Private Key field, either copy and paste your certificate's private key into the text box (include the header and footer), or click Read from a file to browse to the private key on your file system. If possible, we recommend using Read from a file to reduce likelihood of error. Note: Private key files end with an extension of .key.
    7. In the Certificate field, either copy and paste your certificate into the text box (include the header and footer), or click Read from a file to browse to the certificate on your file system. If possible, we recommend using Read from a file to reduce likelihood of error. Note: Certificate files end with an extension of .crt.
    8. Click Create.

    2. Add the Secret to an Ingress​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to deploy your ingress and click Service Discovery > Ingresses.
    3. Click Create.
    4. Select the Namespace of the ingress.
    5. Enter a Name for the ingress.
    6. In the Certificates tab, select the secret containing your certificate and private key.
    7. Click Create.

    What's Next?​

    Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see Adding Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html index 590fffe6a4b..9d61ef038c8 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html @@ -5,13 +5,13 @@ Background Information on HPAs | Rancher Manager - +
    Version: v2.6

    Background Information on HPAs

    The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down. This section provides explanation on how HPA works with Kubernetes.

    Why Use Horizontal Pod Autoscaler?​

    Using HPA, you can automatically scale the number of pods within a replication controller, deployment, or replica set up or down. HPA automatically scales the number of pods that are running for maximum efficiency. Factors that affect the number of pods include:

    • A minimum and maximum number of pods allowed to run, as defined by the user.
    • Observed CPU/memory use, as reported in resource metrics.
    • Custom metrics provided by third-party metrics application like Prometheus, Datadog, etc.

    HPA improves your services by:

    • Releasing hardware resources that would otherwise be wasted by an excessive number of pods.
    • Increase/decrease performance as needed to accomplish service level agreements.

    How HPA Works​

    HPA Schema

    HPA is implemented as a control loop, with a period controlled by the kube-controller-manager flags below:

    FlagDefaultDescription
    --horizontal-pod-autoscaler-sync-period30sHow often HPA audits resource/custom metrics in a deployment.
    --horizontal-pod-autoscaler-downscale-delay5m0sFollowing completion of a downscale operation, how long HPA must wait before launching another downscale operations.
    --horizontal-pod-autoscaler-upscale-delay3m0sFollowing completion of an upscale operation, how long HPA must wait before launching another upscale operation.

    For full documentation on HPA, refer to the Kubernetes Documentation.

    Horizontal Pod Autoscaler API Objects​

    HPA is an API resource in the Kubernetes autoscaling API group. The current stable version is autoscaling/v1, which only includes support for CPU autoscaling. To get additional support for scaling based on memory and custom metrics, use the beta version instead: autoscaling/v2beta1.

    For more information about the HPA API object, see the HPA GitHub Readme.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html index cf519e1b2ab..521e80c9aae 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html @@ -5,7 +5,7 @@ Managing HPAs with kubectl | Rancher Manager - + @@ -22,7 +22,7 @@ I0724 10:18:45.699620 1 api.go:93] Response Body: {"status":&quo I0724 10:18:45.699939 1 wrap.go:42] GET /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/%2A/fs_read?labelSelector=app%3Dhello-world: (12.431262ms) 200 [[kube-controller-manager/v1.10.1 (linux/amd64) kubernetes/d4ab475/system:serviceaccount:kube-system:horizontal-pod-autoscaler] 10.42.0.0:24268] I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} ...

    1. Check that the metrics API is accessible from kubectl.

    • If you are accessing the cluster directly, enter your Server URL in the kubectl config in the following format: https://<Kubernetes_URL>:6443.

      # kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    • If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: https://<RANCHER_URL>/k8s/clusters/<CLUSTER_ID>. Add the suffix /k8s/clusters/<CLUSTER_ID> to API path.

      # kubectl get --raw /k8s/clusters/<CLUSTER_ID>/apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html index da048ed4398..e5ad6d3b7bb 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html @@ -5,13 +5,13 @@ Managing HPAs with the Rancher UI | Rancher Manager - +
    Version: v2.6

    Managing HPAs with the Rancher UI

    The Rancher UI supports creating, managing, and deleting HPAs. You can configure CPU or memory usage as the metric that the HPA uses to scale.

    If you want to create HPAs that scale based on other metrics than CPU and memory, refer to Configuring HPA to Scale Using Custom Metrics with Prometheus.

    Creating an HPA​

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster you want to create an HPA in and click Explore.

    3. In the left navigation bar, click Service Discovery > HorizontalPodAutoscalers.

    4. Click Create.

    5. Select a Namespace for the HPA.

    6. Enter a Name for the HPA.

    7. Select a Target Reference as scale target for the HPA.

    8. Specify the Minimum Replicas and Maximum Replicas for the HPA.

    9. Configure the metrics for the HPA. You can choose memory or CPU usage as the metric that will cause the HPA to scale the service up or down. In the Quantity field, enter the percentage of the workload's memory or CPU usage that will cause the HPA to scale the service. To configure other HPA metrics, including metrics available from Prometheus, you need to manage HPAs using kubectl.

    10. Click Create to create the HPA.

    Result:

    The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view.

    Get HPA Metrics and Status​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that has the HPA and click Explore.
    3. In the left navigation bar, click Service Discovery > HorizontalPodAutoscalers. The HorizontalPodAutoscalers page shows the number of current replicas.

    For more detailed metrics and status of a specific HPA, click the name of the HPA. This leads to the HPA detail page.

    Deleting an HPA​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that has the HPA you want to delete and click Explore.
    3. In the left navigation bar, click Service Discovery > HorizontalPodAutoscalers.
    4. Click Resources > HPA.
    5. Find the HPA which you would like to delete and click ⋮ > Delete.
    6. Click Delete to confirm.
    Result:

    The HPA is deleted from the current cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html index b3552a62fce..ab1287d8545 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html @@ -5,14 +5,14 @@ Testing HPAs with kubectl | Rancher Manager - +
    Version: v2.6

    Testing HPAs with kubectl

    This document describes how to check the status of your HPAs after scaling them up or down with your load testing tool. For information on how to check the status from the Rancher UI (at least version 2.3.x), refer to Managing HPAs with the Rancher UI.

    For HPA to work correctly, service deployments should have resources request definitions for containers. Follow this hello-world example to test if HPA is working correctly.

    1. Configure kubectl to connect to your Kubernetes cluster.

    2. Copy the hello-world deployment manifest below.

      Hello World Manifest
      apiVersion: apps/v1beta2
      kind: Deployment
      metadata:
        labels:
          app: hello-world
        name: hello-world
        namespace: default
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: hello-world
        strategy:
          rollingUpdate:
            maxSurge: 1
            maxUnavailable: 0
          type: RollingUpdate
        template:
          metadata:
            labels:
              app: hello-world
          spec:
            containers:
            - image: rancher/hello-world
              imagePullPolicy: Always
              name: hello-world
              resources:
                requests:
                  cpu: 500m
                  memory: 64Mi
              ports:
              - containerPort: 80
                protocol: TCP
            restartPolicy: Always
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: hello-world
        namespace: default
      spec:
        ports:
        - port: 80
          protocol: TCP
          targetPort: 80
        selector:
          app: hello-world

    3. Deploy it to your cluster.

      # kubectl create -f <HELLO_WORLD_MANIFEST>

    4. Copy one of the HPAs below based on the metric type you're using:

      Hello World HPA: Resource Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 1000Mi
      Hello World HPA: Custom Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 100Mi
        - type: Pods
          pods:
            metricName: cpu_system
            targetAverageValue: 20m

    5. View the HPA info and description. Confirm that metric data is shown.

      Resource Metrics
      1. Enter the following commands.
        # kubectl get hpa
        NAME          REFERENCE                TARGETS                     MINPODS   MAXPODS   REPLICAS   AGE
        hello-world   Deployment/hello-world   1253376 / 100Mi, 0% / 50%   1         10        1          6m
        # kubectl describe hpa
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 20:21:16 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             1253376 / 100Mi
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>
      Custom Metrics
      1. Enter the following command.
        # kubectl describe hpa
        You should receive the output that follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Tue, 24 Jul 2018 18:36:28 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             3514368 / 100Mi
          "cpu_system" on pods:                                0 / 20m
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>

    6. Generate a load for the service to test that your pods autoscale as intended. You can use any load-testing tool (Hey, Gatling, etc.), but we're using Hey.

    7. Test that pod autoscaling works as intended.

      To Test Autoscaling Using Resource Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to two pods based on CPU Usage.

      1. View your HPA.
        # kubectl describe hpa
        You should receive output similar to what follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             10928128 / 100Mi
          resource cpu on pods  (as a percentage of request):  56% (280m) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:
          Type    Reason             Age   From                       Message
          ----    ------             ----  ----                       -------
          Normal  SuccessfulRescale  13s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm you've scaled to two pods.
           # kubectl get pods
        You should receive output similar to what follows:
           NAME                                                     READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-k8ph2                             1/1       Running   0          1m
           hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Upscale to 3 pods: CPU Usage Up to Target

      Use your load testing tool to upscale to 3 pods based on CPU usage with horizontal-pod-autoscaler-upscale-delay set to 3 minutes.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             9424896 / 100Mi
             resource cpu on pods  (as a percentage of request):  66% (333m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  4m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
         NAME                                                     READY     STATUS    RESTARTS   AGE
         hello-world-54764dfbf8-f46kh                             0/1       Running   0          1m
         hello-world-54764dfbf8-k8ph2                             1/1       Running   0          5m
         hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing to scale down to 1 pod when all metrics are below target for horizontal-pod-autoscaler-downscale-delay (5 minutes by default).

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             10070016 / 100Mi
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  6m    horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  1s    horizontal-pod-autoscaler  New size: 1; reason: All metrics below target

      To Test Autoscaling Using Custom Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale two pods based on CPU usage.

      1. Enter the following command.
          # kubectl describe hpa
        You should receive output similar to what follows.
          Name:                                                  hello-world
          Namespace:                                             default
          Labels:                                                <none>
          Annotations:                                           <none>
          CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
          Reference:                                             Deployment/hello-world
          Metrics:                                               ( current / target )
            resource memory on pods:                             8159232 / 100Mi
            "cpu_system" on pods:                                7m / 20m
            resource cpu on pods  (as a percentage of request):  64% (321m) / 50%
          Min replicas:                                          1
          Max replicas:                                          10
          Conditions:
            Type            Status  Reason              Message
            ----            ------  ------              -------
            AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
            ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
            ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
          Events:
            Type    Reason             Age   From                       Message
            ----    ------             ----  ----                       -------
            Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm two pods are running.
          # kubectl get pods
        You should receive output similar to what follows.
              NAME                           READY     STATUS    RESTARTS   AGE
              hello-world-54764dfbf8-5pfdr   1/1       Running   0          3s
              hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 3 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to three pods when the cpu_system usage limit is up to target.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows:
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             8374272 / 100Mi
             "cpu_system" on pods:                                27m / 20m
             resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  3s    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows:
           # kubectl get pods
           NAME                           READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-5pfdr   1/1       Running   0          3m
           hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
           hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 4 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale to four pods based on CPU usage. horizontal-pod-autoscaler-upscale-delay is set to three minutes by default.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8374272 / 100Mi
              "cpu_system" on pods:                                27m / 20m
              resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  4s    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm four pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
          NAME                           READY     STATUS    RESTARTS   AGE
          hello-world-54764dfbf8-2p9xb   1/1       Running   0          5m
          hello-world-54764dfbf8-5pfdr   1/1       Running   0          2m
          hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
          hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing tool to scale down to one pod when all metrics below target for horizontal-pod-autoscaler-downscale-delay.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive similar output to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8101888 / 100Mi
              "cpu_system" on pods:                                8m / 20m
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  8m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
              Normal   SuccessfulRescale             13s               horizontal-pod-autoscaler  New size: 1; reason: All metrics below target
      2. Enter the following command to confirm a single pods is running.
            # kubectl get pods
        You should receive output similar to what follows.
            NAME                           READY     STATUS    RESTARTS   AGE
            hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html index bfa40b3d3a4..5891d4a109e 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html @@ -5,13 +5,13 @@ Kubernetes Registry and Docker Registry | Rancher Manager - +
    Version: v2.6

    Kubernetes Registry and Docker Registry

    Registries are Kubernetes secrets containing credentials used to authenticate with private Docker registries.

    The word "registry" can mean two things, depending on whether it is used to refer to a Docker or Kubernetes registry:

    • A Docker registry contains Docker images that you can pull in order to use them in your deployment. The registry is a stateless, scalable server side application that stores and lets you distribute Docker images.
    • The Kubernetes registry is an image pull secret that your deployment uses to authenticate with a Docker registry.

    Deployments use the Kubernetes registry secret to authenticate with a private Docker registry and then pull a Docker image hosted on it.

    Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl.

    Creating a Registry in Namespaces

    Prerequisite:

    You must have a private registry available to use.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to add a registry and click Explore.

    3. In the left navigation, click either Storage > Secrets or More Resources > Core > Secrets.

    4. Click Create.

    5. Click Registry.

    6. Enter a Name for the registry.

      note

      Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace.

    7. Select a namespace for the registry.

    8. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password.

    9. Click Save.

    Result:

    • Your secret is added to the namespace you chose.
    • You can view the secret in the Rancher UI by clicking either Storage > Secrets or More Resources > Core > Secrets.
    • Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope.

    Creating a Registry in Projects

    Prerequisites:

    You must have a private registry available to use.

    Before v2.6, secrets were required to be in a project scope. Projects are no longer required, and you may use the namespace scope instead. As a result, the Rancher UI was updated to reflect this new functionality. However, you may still create a project-scoped registry if desired. Use the following steps to do so:

    1. In the upper left corner, click ☰ > Global Settings in the dropdown.

    2. Click Feature Flags.

    3. Go to the legacy feature flag and click Activate.

    4. In the upper left corner, click ☰ > Cluster Management.

    5. Go to the cluster where you want to add a registry and click Explore.

    6. In the left navigation, click either Storage > Secrets or More Resources > Core > Secrets.

    7. Click Create.

    8. Click Registry.

    9. In the top navigation bar, filter to see only one project.

    10. Enter a Name for the registry.

      note

      Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace.

    11. Select a namespace for the registry.

    12. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password.

    13. Click Save.

    Result:

    • Your secret is added to the individual project you chose.
    • You can view the secret in the Rancher UI by clicking either Storage > Secrets or More Resources > Core > Secrets.
    • Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope.
    note

    Project-scoped registries on the local cluster are only visible when a single project is selected.

    Using a Private Registry

    You can deploy a workload with an image from a private registry through the Rancher UI, or with kubectl.

    Using the Private Registry with the Rancher UI​

    To deploy a workload with an image from your private registry,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to deploy a workload and click Explore.
    3. Click Workload.
    4. Click Create.
    5. Select the type of workload you want to create.
    6. Enter a unique name for the workload and choose a namespace.
    7. In the Container Image field, enter the URL of the path to the image in your private registry. For example, if your private registry is on Quay.io, you could use quay.io/<Quay profile name>/<Image name>.
    8. Click Create.

    Result: Your deployment should launch, authenticate using the private registry credentials you added in the Rancher UI, and pull the Docker image that you specified.

    Using the Private Registry with kubectl​

    When you create the workload using kubectl, you need to configure the pod so that its YAML has the path to the image in the private registry. You also have to create and reference the registry secret because the pod only automatically gets access to the private registry credentials if it is created in the Rancher UI.

    The secret has to be created in the same namespace where the workload gets deployed.

    Below is an example pod.yml for a workload that uses an image from a private registry. In this example, the pod uses an image from Quay.io, and the .yml specifies the path to the image. The pod authenticates with the registry using credentials stored in a Kubernetes secret called testquay, which is specified in spec.imagePullSecrets in the name field:

    apiVersion: v1
    kind: Pod
    metadata:
      name: private-reg
    spec:
      containers:
      - name: private-reg-container
        image: quay.io/<Quay profile name>/<image name>
      imagePullSecrets:
      - name: testquay

    In this example, the secret named testquay is in the default namespace.

    You can use kubectl to create the secret with the private registry credentials. This command creates the secret named testquay:

    kubectl create secret docker-registry testquay \
        --docker-server=quay.io \
        --docker-username=<Profile name> \
        --docker-password=<password>

    To see how the secret is stored in Kubernetes, you can use this command:

    kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

    The result looks like this:

    {"auths":{"quay.io":{"username":"<Profile name>","password":"<password>","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}}

    After the workload is deployed, you can check if the image was pulled successfully:

    kubectl get events

    The result should look like this:

    14s         Normal    Scheduled          Pod    Successfully assigned default/private-reg2 to minikube
    11s         Normal    Pulling            Pod    pulling image "quay.io/<Profile name>/<image name>"
    10s         Normal    Pulled             Pod    Successfully pulled image "quay.io/<Profile name>/<image name>"

    For more information, refer to the Kubernetes documentation on creating a pod that uses your secret.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html index a4c812e838a..940a5312da8 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html @@ -5,13 +5,13 @@ Adding Ingresses | Rancher Manager - +
    Version: v2.6

    Adding Ingresses

    Ingresses can be added for workloads to provide load balancing, SSL termination and host/path based routing. When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that you want to add an ingress to and click Explore.
    3. Click Service Discovery > Ingresses.
    4. Click Create.
    5. Select an existing Namespace from the drop-down list.
    6. Enter a Name for the ingress.
    7. Create ingress forwarding Rules. For help configuring the rules, refer to this section. If any of your ingress rules handle requests for encrypted ports, add a certificate to encrypt/decrypt communications.
    8. Optional: click Add Rule to create additional ingress rules. For example, after you create ingress rules to direct requests for your hostname, you'll likely want to create a default backend to handle 404s.
    9. Click Create at the bottom right.

    Result: Your ingress is added to the project. The ingress begins enforcing your ingress rules.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.html index 3dee7be5b56..6708687c807 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/ingress-configuration.html @@ -5,13 +5,13 @@ Ingress Configuration | Rancher Manager - +
    Version: v2.6

    Ingress Configuration

    NGINX Ingress controller changes in Kubernetes v1.21​

    For Kubernetes v1.21 and up, the NGINX Ingress controller no longer runs in hostNetwork but uses hostPorts for port 80 and port 443. This was done so the admission webhook can be configured to be accessed using ClusterIP so it can only be reached inside the cluster.

    Ingress Rule Configuration

    Specify a hostname to use​

    If you use this option, ingress routes requests for a hostname to the service or workload that you specify.

    1. Enter the Request Host that your ingress will handle request forwarding for. For example, www.mysite.com.
    2. Add a Target Service.
    3. Optional: If you want specify a workload or service when a request is sent to a particular hostname path, add a Path for the target. For example, if you want requests for www.mysite.com/contact-us to be sent to a different service than www.mysite.com, enter /contact-us in the Path field. Typically, the first rule that you create does not include a path.
    4. Enter the Port number that each target operates on.

    Certificates​

    note

    You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see Adding SSL Certificates.

    1. When creating an ingress, click the Certificates tab.
    2. Click Add Certificate.
    3. Select a Certificate - Secret Name from the drop-down list.
    4. Enter the host using encrypted communication.
    5. To add additional hosts that use the certificate, click Add Hosts.

    Labels and Annotations​

    Add Labels and/or Annotations to provide metadata for your ingress.

    For a list of annotations available for use, see the Nginx Ingress Controller Documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html index 5875d0c3b04..0064ec9e386 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html @@ -5,13 +5,13 @@ Layer 4 and Layer 7 Load Balancing | Rancher Manager - +
    Version: v2.6

    Layer 4 and Layer 7 Load Balancing

    Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing.

    Layer-4 Load Balancer​

    Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic.

    Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single globally managed config-map can be used to expose services on NGINX or third-party ingress.

    note

    It is possible to deploy a cluster with a non-cloud load balancer, such as MetalLB. However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE.

    Support for Layer-4 Load Balancing​

    Support for layer-4 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-4 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GCE cloud provider
    Azure AKSSupported by Azure cloud provider
    RKE on EC2Supported by AWS cloud provider
    RKE on DigitalOceanLimited NGINX or third-party Ingress*
    RKE on vSphereLimited NGINX or third party-Ingress*
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Limited NGINX or third-party Ingress*
    Third-party MetalLBLimited NGINX or third-party Ingress*

    * Services can be exposed through a single globally managed config-map.

    Layer-7 Load Balancer​

    Layer-7 load balancer (or the ingress controller) supports host and path-based load balancing and SSL termination. Layer-7 load balancer only forwards HTTP and HTTPS traffic and therefore they listen on ports 80 and 443 only. Cloud providers such as Amazon and Google support layer-7 load balancer. In addition, RKE clusters deploys the Nginx Ingress Controller.

    Support for Layer-7 Load Balancing​

    Support for layer-7 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-7 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GKE cloud provider
    Azure AKSNot Supported
    RKE on EC2Nginx Ingress Controller
    RKE on DigitalOceanNginx Ingress Controller
    RKE on vSphereNginx Ingress Controller
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Nginx Ingress Controller

    Host Names in Layer-7 Load Balancer​

    Some cloud-managed layer-7 load balancers (such as the ALB ingress controller on AWS) expose DNS addresses for ingress rules. You need to map (via CNAME) your domain name to the DNS address generated by the layer-7 load balancer.

    Other layer-7 load balancers, such as the Google Load Balancer or Nginx Ingress Controller, directly expose one or more IP addresses. Google Load Balancer provides a single routable IP address. Nginx Ingress Controller exposes the external IP of all nodes that run the Nginx Ingress Controller. You can do either of the following:

    1. Configure your own DNS to map (via A records) your domain name to the IP addresses exposes by the Layer-7 load balancer.
    2. Ask Rancher to generate an xip.io host name for your ingress rule. Rancher will take one of your exposed IPs, say a.b.c.d, and generate a host name <ingressname>.<namespace>.a.b.c.d.xip.io.

    The benefit of using xip.io is that you obtain a working entrypoint URL immediately after you create the ingress rule. Setting up your own domain name, on the other hand, requires you to configure DNS servers and wait for DNS to propagate.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html index 24610366d8d..13c59dfcfa9 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html @@ -5,13 +5,13 @@ Secrets | Rancher Manager - +
    Version: v2.6

    Secrets

    Secrets store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs.

    note

    This page is about secrets in general. For details on setting up a private registry, refer to the section on registries.

    When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    Creating Secrets in Namespaces

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to add a secret and click Explore.

    3. To navigate to secrets, you may click either Storage > Secrets or More Resources > Core > Secrets.

    4. Click Create.

    5. Select the type of secret you want to create.

    6. Select a Namespace for the secret.

    7. Enter a Name for the secret.

      note

      Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace.

    8. From Data, click Add to add a key-value pair. Add as many values as you need.

      tip

      You can add multiple key value pairs to the secret by copying and pasting.

    9. Click Save.

    Result: Your secret is added to the namespace you chose. You can view the secret in the Rancher UI by clicking either Storage > Secrets or More Resources > Core > Secrets.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    Creating Secrets in Projects

    Before v2.6, secrets were required to be in a project scope. Projects are no longer required, and you may use the namespace scope instead. As a result, the Rancher UI was updated to reflect this new functionality. However, you may still create project-scoped secrets if desired. Note that you have to first enable the legacy feature flag and look at a single project to do so. Use the following steps to set up your project-level secret:

    1. In the upper left corner, click ☰ > Global Settings in the dropdown.
    2. Click Feature Flags.
    3. Go to the legacy feature flag and click Activate.
    4. In the upper left corner, click ☰ > Cluster Management in the dropdown.
    5. Go to the cluster that you created and click Explore.
    6. Click Legacy > Projects.
    7. In the top navigation bar, filter to see only one project.
    8. In the left navigation bar, click Secrets.
    9. Click Add Secret.

    Result: Your secret is added to the individual project you chose. You can view the secret in the Rancher UI by clicking either Storage > Secrets or More Resources > Core > Secrets.

    note

    Project-scoped secrets on the local cluster are only visible when a single project is selected.

    What's Next?

    Now that you have a secret added to a namespace, you can add it to a workload that you deploy.

    For more information on adding secret to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html index 32662c7c4fd..5b5fc11a080 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html @@ -5,13 +5,13 @@ Adding a Sidecar | Rancher Manager - +
    Version: v2.6

    Adding a Sidecar

    A sidecar is a container that extends or enhances the main container in a pod. The main container and the sidecar share a pod, and therefore share the same network space and storage. You can add sidecars to existing workloads by using the Add a Sidecar option.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to add a sidecar and click Explore.

    3. In the left navigation bar, click Workload.

    4. Find the workload that you want to extend. Select ⋮ > + Add Sidecar.

    5. Enter a Name for the sidecar.

    6. In the General section, select a sidecar type. This option determines if the sidecar container is deployed before or after the main container is deployed.

      • Standard Container:

        The sidecar container is deployed after the main container.

      • Init Container:

        The sidecar container is deployed before the main container.

    7. From the Container Image field, enter the name of the container image that you want to deploy in support of the main container. During deployment, Rancher pulls this image from Docker Hub. Enter the name exactly as it appears on Docker Hub.

    8. Set the remaining options. You can read about them in Deploying Workloads.

    9. Click Launch.

    Result: The sidecar is deployed according to your parameters. Following its deployment, you can view the sidecar by selecting ⋮ icon (...) > Edit for the main deployment.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html index 332b7f532be..8302582771c 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Version: v2.6

    Deploying Workloads

    Deploy a workload to run an application in one or more containers.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to upgrade a workload and click Explore.

    3. In the left navigation bar, click Workload.

    4. Click Create.

    5. Choose the type of workload.

    6. Select the namespace where the workload will be deployed.

    7. Enter a Name for the workload.

    8. From the Container Image field, enter the name of the Docker image that you want to deploy to the project, optionally prefacing it with the registry host (e.g. quay.io, registry.gitlab.com, etc.). During deployment, Rancher pulls this image from the specified public or private registry. If no registry host is provided, Rancher will pull the image from Docker Hub. Enter the name exactly as it appears in the registry server, including any required path, and optionally including the desired tag (e.g. registry.gitlab.com/user/path/image:tag). If no tag is provided, the latest tag will be automatically used.

    9. Either select an existing namespace, or click Add to a new namespace and enter a new namespace.

    10. Click Add Port to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see Services.

    11. Configure the remaining options:

      • Environment Variables

        Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or ConfigMap.

      • Node Scheduling

      • Health Check

      • Volumes

        Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a ConfigMap.

        When you are deploying a Stateful Set, you should use a Volume Claim Template when using Persistent Volumes. This will ensure that Persistent Volumes are created dynamically when you scale your Stateful Set.

      • Scaling/Upgrade Policy

      Amazon Note for Volumes:

      To mount an Amazon EBS volume:

    12. Click Show Advanced Options and configure:

      • Command
      • Networking
      • Labels & Annotations
      • Security and Host Config

    13. Click Launch.

    Result: The workload is deployed to the chosen namespace. You can view the workload's status from the project's Workloads view.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html index 7b13e336a34..e536cb6a171 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html @@ -5,13 +5,13 @@ Rolling Back Workloads | Rancher Manager - +
    Version: v2.6

    Rolling Back Workloads

    Sometimes there is a need to rollback to the previous version of the application, either for debugging purposes or because an upgrade did not go as planned.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to upgrade a workload and click Explore.

    3. In the left navigation bar, click Workload.

    4. Find the workload that you want to rollback and select ⋮ > Rollback.

    5. Choose the revision that you want to roll back to. Click Rollback.

    Result: Your workload reverts to the previous version that you chose. Wait a few minutes for the action to complete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html index 8a9b8b9b7d3..99dc5d0e6d0 100644 --- a/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html +++ b/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html @@ -5,13 +5,13 @@ Upgrading Workloads | Rancher Manager - +
    Version: v2.6

    Upgrading Workloads

    When a new version of an application image is released on Docker Hub, you can upgrade any workloads running a previous version of the application to the new one.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to upgrade a workload and click Explore.

    3. In the left navigation bar, click Workload.

    4. Find the workload that you want to upgrade and select ⋮ > Edit Config.

    5. Update the Container Image and any options that you want to change.

    6. Review and edit the workload's Scaling and Upgrade Policy.

      These options control how the upgrade rolls out to containers that are currently running. For example, for scalable deployments, you can choose whether you want to stop old pods before deploying new ones, or vice versa, as well as the upgrade batch size.

    7. Click Save.

    Result: The workload begins upgrading its containers, per your specifications. Note that scaling up the deployment or updating the upgrade/scaling policy won't result in the pods recreation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/index.html b/index.html index 87615ada274..6e070ad64dc 100644 --- a/index.html +++ b/index.html @@ -5,13 +5,13 @@ Rancher 2.6 | Rancher Manager - +
    Version: v2.6

    Rancher 2.6

    Rancher is a Kubernetes management tool to deploy and run clusters anywhere and on any provider.

    Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.

    Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.

    It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes Fleet to help you automatically deploy and upgrade workloads.

    Rancher is a complete container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/about-authentication.html b/pages-for-subheaders/about-authentication.html index ed4518eed7c..b8bc42e6ff2 100644 --- a/pages-for-subheaders/about-authentication.html +++ b/pages-for-subheaders/about-authentication.html @@ -5,13 +5,13 @@ Authentication | Rancher Manager - +
    Version: v2.6

    Authentication

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters.

    This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.

    External vs. Local Authentication​

    The Rancher authentication proxy integrates with the following external authentication services.

    Auth Service
    Microsoft Active Directory
    GitHub
    Microsoft Azure AD
    FreeIPA
    OpenLDAP
    Microsoft AD FS
    PingIdentity
    Keycloak (OIDC)
    Keycloak (SAML)
    Okta
    Google OAuth
    Shibboleth

    However, Rancher also provides [local authentication](/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users).

    In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if your external authentication provider is unavailable or undergoing maintenance.

    Users and Groups​

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see Role Based Access Control.

    note

    Local authentication does not support creating or managing groups.

    For more information, see Users and Groups

    Scope of Rancher Authorization​

    After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available:

    Access LevelDescription
    Allow any valid UsersAny user in the authorization service can access Rancher. We generally discourage use of this setting!
    Allow members of Clusters, Projects, plus Authorized Users and OrganizationsAny user in the authorization service and any group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any user in the authentication service or group you add to the Authorized Users and Organizations list may log in to Rancher.
    Restrict access to only Authorized Users and OrganizationsOnly users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher.

    To set the Rancher access level for users in the authorization service, follow these steps:

    1. In the upper left corner, click ☰ > Users & Authentication.
    2. In the left navigation bar, click Auth Provider.
    3. After setting up the configuration details for an auth provider, use the Site Access options to configure the scope of user authorization. The table above explains the access level for each option.
    4. Optional: If you choose an option other than Allow any valid Users, you can add users to the list of authorized users and organizations by searching for them in the text field that appears.
    5. Click Save.

    Result: The Rancher access configuration settings are applied.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    External Authentication Configuration and Principal Users​

    Configuration of external authentication requires:

    • A local user assigned the administrator role, called hereafter the local principal.
    • An external user that can authenticate with your external authentication service, called hereafter the external principal.

    Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects.

    1. Sign into Rancher as the local principal and complete configuration of external authentication.

      Sign In

    2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.

      Principal ID Sharing

    3. After you complete configuration, Rancher automatically signs out the local principal.

      Sign Out Local Principal

    4. Then, Rancher automatically signs you back in as the external principal.

      Sign In External Principal

    5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.

      Sign In External Principal

    6. The external principal and the local principal share the same access rights.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/about-provisioning-drivers.html b/pages-for-subheaders/about-provisioning-drivers.html index 99d6dd21547..3cea2aef3bc 100644 --- a/pages-for-subheaders/about-provisioning-drivers.html +++ b/pages-for-subheaders/about-provisioning-drivers.html @@ -5,13 +5,13 @@ Provisioning Drivers | Rancher Manager - +
    Version: v2.6

    Provisioning Drivers

    Drivers in Rancher allow you to manage which providers can be used to deploy hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    Rancher Drivers​

    With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it.

    There are two types of drivers within Rancher:

    Cluster Drivers​

    Cluster drivers are used to provision hosted Kubernetes clusters, such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.

    By default, Rancher has activated several hosted Kubernetes cloud providers including:

    There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:

    Node Drivers​

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:

    There are several other node drivers that are disabled by default, but are packaged in Rancher:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/about-rke1-templates.html b/pages-for-subheaders/about-rke1-templates.html index 98d3b753128..5098a216ce3 100644 --- a/pages-for-subheaders/about-rke1-templates.html +++ b/pages-for-subheaders/about-rke1-templates.html @@ -5,13 +5,13 @@ RKE Templates | Rancher Manager - +
    Version: v2.6

    RKE Templates

    RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters.

    RKE is the Rancher Kubernetes Engine, which is the tool that Rancher uses to provision Kubernetes clusters.

    With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users.

    RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced.

    Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users.

    If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters.

    The core features of RKE templates allow DevOps and security teams to:

    • Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices
    • Prevent less technical users from making uninformed choices when provisioning clusters
    • Share different templates with different sets of users and groups
    • Delegate ownership of templates to users who are trusted to make changes to them
    • Control which users can create templates
    • Require users to create clusters from a template

    Configurable Settings​

    RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider:

    • Cloud provider options
    • Pod security options
    • Network providers
    • Ingress controllers
    • Network security configuration
    • Network plugins
    • Private registry URL and credentials
    • Add-ons
    • Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services

    The add-on section of an RKE template is especially powerful because it allows a wide range of customization options.

    Scope of RKE Templates​

    RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider.

    RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to RKE Templates and Hardware.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    The settings of an existing cluster can be saved as an RKE template. This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the template is updated, and the cluster is upgraded to use a newer version of the template. The new template can also be used to create new clusters.

    Example Scenarios​

    When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users.

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    Some of the example scenarios include the following:

    Template Management​

    When you create an RKE template, it is available in the Rancher UI from the Cluster Management view under RKE Templates. When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public.

    Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings.

    RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision.

    In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the Allow User Override toggle over each setting in the Rancher UI when the template is created.

    For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option.

    The documents in this section explain the details of RKE template management:

    An example YAML configuration file for a template is provided for reference.

    Applying Templates​

    You can create a cluster from a template that you created, or from a template that has been shared with you.

    If the RKE template owner creates a new revision of the template, you can upgrade your cluster to that revision.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    Standardizing Hardware​

    RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, one option is to use RKE templates in conjunction with other tools.

    Another option is to use cluster templates, which include node pool configuration options, but don't provide configuration enforcement.

    YAML Customization​

    If you define an RKE template as a YAML file, you can modify this example RKE template YAML. The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the rancher_kubernetes_engine_config directive in the YAML.

    The RKE documentation also has annotated cluster.yml files that you can use for reference.

    For guidance on available options, refer to the RKE documentation on cluster configuration.

    Add-ons​

    The add-on section of the RKE template configuration file works the same way as the add-on section of a cluster configuration file.

    The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster.

    Some things you could do with add-ons include:

    • Install applications on the Kubernetes cluster after it starts
    • Install plugins on nodes that are deployed with a Kubernetes daemonset
    • Automatically set up namespaces, service accounts, or role binding

    The RKE template configuration must be nested within the rancher_kubernetes_engine_config directive. To set add-ons, when creating the template, you will click Edit as YAML. Then use the addons directive to add a manifest, or the addons_include directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the user-defined add-ons documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/about-the-api.html b/pages-for-subheaders/about-the-api.html index 21a7b191ae7..0a2461a19d2 100644 --- a/pages-for-subheaders/about-the-api.html +++ b/pages-for-subheaders/about-the-api.html @@ -5,13 +5,13 @@ API | Rancher Manager - +
    Version: v2.6

    API

    How to use the API​

    The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it:

    1. Click on your user avatar in the upper right corner.
    2. Click Account & API Keys.
    3. Under the API Keys section, find the API Endpoint field and click the link. The link will look something like https://<RANCHER_FQDN>/v3, where <RANCHER_FQDN> is the fully qualified domain name of your Rancher deployment.

    Authentication​

    API requests must include authentication information. Authentication is done with HTTP basic authentication using API Keys. API keys can create new clusters and have access to multiple clusters via /v3/clusters/. Cluster and project roles apply to these keys and restrict what clusters and projects the account can see and what actions they can take.

    By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. For details on how to invalidate them, refer to the API tokens page.

    Making requests​

    The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, see here.

    • Every type has a Schema which describes:
      • The URL to get to the collection of this type of resources
      • Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
      • Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
      • Every field that filtering is allowed on
      • What HTTP verb methods are available for the collection itself, or for individual resources in the collection.

    • So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a X-Api-Schemas header. From there you can follow the collection link on each schema to know where to list resources, and other links inside of the returned resources to get any other information.

    • In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (/v3/<type>) or get a specific resource (/v3/<type>/<id>). Anything deeper than that is subject to change in future releases.

    • Resources have relationships between each other called links. Each resource includes a map of links with the name of the link and the URL to retrieve that information. Again you should GET the resource and then follow the URL in the links map, not construct these strings yourself.

    • Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP POST to the URL in the actions map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.

    • To edit a resource, send a HTTP PUT to the links.update link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.

    • To delete a resource, send a HTTP DELETE to the links.remove link on the resource. If the link is missing then you don't have permission to update the resource.

    • To create a new resource, HTTP POST to the collection URL in the schema (which is /v3/<type>).

    Filtering​

    Most collections can be filtered on the server-side by common fields using HTTP query parameters. The filters map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just field=value. Modifiers can be added to the field name, e.g. field_gt=42 for "field is greater than 42". See the API spec for full details.

    Sorting​

    Most collections can be sorted on the server-side by common fields using HTTP query parameters. The sortLinks map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.

    Pagination​

    API responses are paginated with a limit of 100 resources per page by default. This can be changed with the limit query parameter, up to a maximum of 1000, e.g. /v3/pods?limit=1000. The pagination map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.

    Capturing Rancher API Calls​

    You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:

    1. In the Rancher UI, go to Cluster Management and click Create.
    2. Click one of the cluster types. This example uses Digital Ocean.
    3. Fill out the form with a cluster name and node template, but don't click Create.
    4. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click Inspect.
    5. In the developer tools, click the Network tab.
    6. On the Network tab, make sure Fetch/XHR is selected.
    7. In the Rancher UI, click Create. In the developer tools, you should see a new network request with the name cluster?_replace=true.
    8. Right-click cluster?_replace=true and click Copy > Copy as cURL.
    9. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/access-clusters.html b/pages-for-subheaders/access-clusters.html index 7c582a75789..8aecacf9a00 100644 --- a/pages-for-subheaders/access-clusters.html +++ b/pages-for-subheaders/access-clusters.html @@ -5,13 +5,13 @@ Cluster Access | Rancher Manager - +
    Version: v2.6

    Cluster Access

    This section is about what tools can be used to access clusters managed by Rancher.

    For information on how to give users permission to access a cluster, see the section on adding users to clusters.

    For more information on roles-based access control, see this section.

    For information on how to set up an authentication system, see this section.

    Rancher UI​

    Rancher provides an intuitive user interface for interacting with your clusters. All options available in the UI use the Rancher API. Therefore any action possible in the UI is also possible in the Rancher CLI or Rancher API.

    kubectl​

    You can use the Kubernetes command-line tool, kubectl, to manage your clusters. You have two options for using kubectl:

    • Rancher kubectl shell: Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part. For more information, see Accessing Clusters with kubectl Shell.
    • Terminal remote connection: You can also interact with your clusters by installing kubectl on your local desktop and then copying the cluster's kubeconfig file to your local ~/.kube/config directory. For more information, see Accessing Clusters with kubectl and a kubeconfig File.

    Rancher CLI​

    You can control your clusters by downloading Rancher's own command-line interface, Rancher CLI. This CLI tool can interact directly with different clusters and projects or pass them kubectl commands.

    Rancher API​

    Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an API key. To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on View in API for any Rancher UI object.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/advanced-configuration.html b/pages-for-subheaders/advanced-configuration.html index 663814768eb..f2b7949d6e8 100644 --- a/pages-for-subheaders/advanced-configuration.html +++ b/pages-for-subheaders/advanced-configuration.html @@ -5,13 +5,13 @@ Advanced Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/advanced-options.html b/pages-for-subheaders/advanced-options.html index 91f1a720005..183a56e7e33 100644 --- a/pages-for-subheaders/advanced-options.html +++ b/pages-for-subheaders/advanced-options.html @@ -5,13 +5,13 @@ Advanced | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/advanced-user-guides.html b/pages-for-subheaders/advanced-user-guides.html index d9f43b274aa..56cccf58616 100644 --- a/pages-for-subheaders/advanced-user-guides.html +++ b/pages-for-subheaders/advanced-user-guides.html @@ -5,13 +5,13 @@ Advanced User Guides | Rancher Manager - +
    Version: v2.6

    Advanced User Guides

    Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.

    It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/air-gapped-helm-cli-install.html b/pages-for-subheaders/air-gapped-helm-cli-install.html index 66eb4404014..bbeda9c2912 100644 --- a/pages-for-subheaders/air-gapped-helm-cli-install.html +++ b/pages-for-subheaders/air-gapped-helm-cli-install.html @@ -5,13 +5,13 @@ Air-Gapped Helm CLI Install | Rancher Manager - +
    Version: v2.6

    Air-Gapped Helm CLI Install

    This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.

    For more information on each installation option, refer to this page.

    Throughout the installation instructions, there will be tabs for each installation option.

    Important:

    If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.

    Installation Outline

    1. Set up infrastructure and private registry
    2. Collect and publish images to your private registry
    3. Set up a Kubernetes cluster (Skip this step for Docker installations)
    4. Install Rancher

    Upgrades

    To upgrade Rancher with Helm CLI in an air gap environment, follow this procedure.

    Next: Prepare your Node(s)​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/amazon-eks-permissions.html b/pages-for-subheaders/amazon-eks-permissions.html index 52c6341768e..9b04c2b98b4 100644 --- a/pages-for-subheaders/amazon-eks-permissions.html +++ b/pages-for-subheaders/amazon-eks-permissions.html @@ -5,13 +5,13 @@ Creating an EKS Cluster | Rancher Manager - +
    Version: v2.6

    Creating an EKS Cluster

    Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this documentation.

    Prerequisites in Amazon Web Services​

    caution

    Deploying to Amazon AWS will incur charges. For more information, refer to the EKS pricing page.

    To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate permissions. For details, refer to the official guide on Amazon EKS Prerequisites.

    Amazon VPC​

    An Amazon VPC is required to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. You can set one up yourself and provide it during cluster creation in Rancher. If you do not provide one during creation, Rancher will create one. For more information, refer to the Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster.

    IAM Policies​

    Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access.

    1. Create a user with programmatic access by following the steps here.

    2. Next, create an IAM policy that defines what this user has access to in your AWS account. It's important to only grant this user minimal access within your account. The minimum permissions required for an EKS cluster are listed here. Follow the steps here to create an IAM policy and attach it to your user.

    3. Finally, follow the steps here to create an access key and secret key for this user.

    Important:

    It's important to regularly rotate your access and secret keys. See this documentation for more information.

    For more detailed information on IAM policies for EKS, refer to the official documentation on Amazon EKS IAM Policies, Roles, and Permissions.

    Create the EKS Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Choose Amazon EKS.
    4. Enter a Cluster Name.
    5. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Fill out the rest of the form. For help, refer to the configuration reference.
    7. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    EKS Cluster Configuration Reference​

    For the full list of EKS cluster configuration options, see this page.

    Architecture​

    The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS.

    Managing Kubernetes Clusters through Rancher's Authentication Proxy

    Architecture

    AWS Service Events​

    To find information on any AWS Service events, please see this page.

    Security and Compliance​

    By default only the IAM user or role that created a cluster has access to it. Attempting to access the cluster with any other user or role without additional configuration will lead to an error. In Rancher, this means using a credential that maps to a user or role that was not used to create the cluster will cause an unauthorized error. For example, an EKSCtl cluster will not register in Rancher unless the credentials used to register the cluster match the role or user used by EKSCtl. Additional users and roles can be authorized to access a cluster by being added to the aws-auth configmap in the kube-system namespace. For a more in-depth explanation and detailed instructions, please see this documentation.

    For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this documentation.

    Tutorial​

    This tutorial on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB.

    Minimum EKS Permissions​

    See this page for the minimum set of permissions necessary to use all functionality of the EKS driver in Rancher.

    Syncing​

    The EKS provisioner can synchronize the state of an EKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

    For information on configuring the refresh interval, refer to this section.

    Troubleshooting​

    If your changes were overwritten, it could be due to the way the cluster data is synced with EKS. Changes shouldn't be made to the cluster from another source, such as in the EKS console, and in Rancher within a five-minute span. For information on how this works and how to configure the refresh interval, refer to Syncing.

    If an unauthorized error is returned while attempting to modify or register the cluster and the cluster was not created with the role or user that your credentials belong to, refer to Security and Compliance.

    For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this documentation.

    Programmatically Creating EKS Clusters​

    The most common way to programmatically deploy EKS clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/authentication-config.html b/pages-for-subheaders/authentication-config.html index f856342fc20..a7d449699ff 100644 --- a/pages-for-subheaders/authentication-config.html +++ b/pages-for-subheaders/authentication-config.html @@ -5,13 +5,13 @@ Authentication Config | Rancher Manager - +
    Version: v2.6

    Authentication Config

    In the following tutorials, you will learn how to manage users and group, create local users, configure Google OAuth, configure Active Directory (AD), configure FreeIPA, configure Azure AD, configure GitHub, configure Keycloak (OIDC), configure Keycloak (SAML), configure PingIdentity (SAML), configure Okta (SAML), configure Shibboleth (SAML), and how to configure Microsoft AD Federation Service (SAML).

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/authentication-permissions-and-global-configuration.html b/pages-for-subheaders/authentication-permissions-and-global-configuration.html index 695dbd0af03..20608b92be8 100644 --- a/pages-for-subheaders/authentication-permissions-and-global-configuration.html +++ b/pages-for-subheaders/authentication-permissions-and-global-configuration.html @@ -5,13 +5,13 @@ Authentication, Permissions and Global Configuration | Rancher Manager - +
    Version: v2.6

    Authentication, Permissions and Global Configuration

    After installation, the system administrator should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.

    First Log In​

    After you log into Rancher for the first time, Rancher will prompt you for a Rancher Server URL.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.

    danger

    After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.

    Authentication​

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.

    For more information how authentication works and how to configure each provider, see Authentication.

    Authorization​

    Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.

    For more information how authorization works and how to customize roles, see Roles Based Access Control (RBAC).

    Pod Security Policies​

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.

    For more information how to create and use PSPs, see Pod Security Policies.

    Provisioning Drivers​

    Drivers in Rancher allow you to manage which providers can be used to provision hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    For more information, see Provisioning Drivers.

    Adding Kubernetes Versions into Rancher​

    With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. v1.15.X), but not intended to upgrade Kubernetes minor versions (i.e. v1.X.0) as Kubernetes tends to deprecate or add APIs between minor versions.

    The information that Rancher uses to provision RKE clusters is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see Rancher Kubernetes Metadata.

    Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision RKE clusters.

    For more information on how metadata works and how to configure metadata config, see Rancher Kubernetes Metadata.

    Enabling Experimental Features​

    Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about feature flags.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/aws-cloud-marketplace.html b/pages-for-subheaders/aws-cloud-marketplace.html index 8cae388637a..72269aa3240 100644 --- a/pages-for-subheaders/aws-cloud-marketplace.html +++ b/pages-for-subheaders/aws-cloud-marketplace.html @@ -5,13 +5,13 @@ AWS Marketplace Integration | Rancher Manager - +
    Version: v2.6

    Overview

    Rancher offers an integration with the AWS Marketplace which allows users to purchase a support contract with SUSE. This integration allows you easily adjust your support needs as you start to support more clusters.

    Limitations

    • You must be running Rancher v2.6.7 or higher
    • Rancher must be deployed with additional metrics enabled.
    • Rancher must be installed on an EKS cluster.
    • You must purchase at least one entitlement to Rancher support through AWS Marketplace.
    • You may need additional setup to support proxy/airgap use cases. See the prerequisites for more information.

    How to Use

    1. Complete the prerequisite steps.
    2. Install the CSP Adapter.

    FAQ

    Can I purchase support for more nodes later on?

    Yes. Simply go to the AWS Marketplace entry that you used to initially purchase support and increase the number of entitlements.

    Can I use multiple instances of Rancher in the same AWS account?

    Yes. However, each cluster that Rancher is installed in will need to adhere to the prerequisites.

    In addition, keep in mind that a given entitlement can only be used by one Rancher management server at a time.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/backup-restore-and-disaster-recovery.html b/pages-for-subheaders/backup-restore-and-disaster-recovery.html index f6d5ed1d3e2..b773544a6bc 100644 --- a/pages-for-subheaders/backup-restore-and-disaster-recovery.html +++ b/pages-for-subheaders/backup-restore-and-disaster-recovery.html @@ -5,13 +5,13 @@ Backups and Disaster Recovery | Rancher Manager - +
    Version: v2.6

    Backups and Disaster Recovery

    In this section, you'll learn how to create backups of Rancher, how to restore Rancher from backup, and how to migrate Rancher to a new Kubernetes cluster.

    The rancher-backup operator is used to backup and restore Rancher on any Kubernetes cluster. This application is a Helm chart, and it can be deployed through the Rancher Apps & Marketplace page, or by using the Helm CLI. The rancher-backup Helm chart is here.

    The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.

    Backup and Restore for Rancher installed with Docker​

    For Rancher installed with Docker, refer to this page to perform backups and this page to perform restores.

    How Backups and Restores Work​

    The rancher-backup operator introduces three custom resources: Backups, Restores, and ResourceSets. The following cluster-scoped custom resource definitions are added to the cluster:

    • backups.resources.cattle.io
    • resourcesets.resources.cattle.io
    • restores.resources.cattle.io

    The ResourceSet defines which Kubernetes resources need to be backed up. The ResourceSet is not available to be configured in the Rancher UI because the values required to back up Rancher are predefined. This ResourceSet should not be modified.

    When a Backup custom resource is created, the rancher-backup operator calls the kube-apiserver to get the resources in the ResourceSet (specifically, the predefined rancher-resource-set) that the Backup custom resource refers to.

    The operator then creates the backup file in the .tar.gz format and stores it in the location configured in the Backup resource.

    When a Restore custom resource is created, the operator accesses the backup .tar.gz file specified by the Restore, and restores the application from that file.

    The Backup and Restore custom resources can be created in the Rancher UI, or by using kubectl apply.

    note

    Refer here for help on restoring an existing backup file into a v1.22 cluster in Rancher v2.6.3.

    Installing the rancher-backup Operator​

    The rancher-backup operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the rancher-backup Helm chart is installed on the Kubernetes cluster running the Rancher server. It is a cluster-admin only feature and available only for the local cluster. (If you do not see rancher-backup in the Rancher UI, you may have selected the wrong cluster.)

    note

    There is a known issue in Fleet that occurs after performing a restoration using the backup-restore-operator: Secrets used for clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer here for a workaround.

    Installing rancher-backup with the Rancher UI​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the local cluster and click Explore.
    3. In the left navigation bar, Apps & Marketplace > Charts.
    4. Click Rancher Backups.
    5. Click Install.
    6. Optional: Configure the default storage location. For help, refer to the configuration section.
    7. Click Install.

    Result: The rancher-backup operator is installed.

    From the Cluster Dashboard, you can see the rancher-backup operator listed under Deployments.

    To configure the backup app in Rancher, go to the left navigation menu and click Rancher Backups.

    RBAC​

    Only the rancher admins and the local cluster’s cluster-owner can:

    • Install the Chart
    • See the navigation links for Backup and Restore CRDs
    • Perform a backup or restore by creating a Backup CR and Restore CR respectively
    • List backups/restores performed so far

    Backing up Rancher​

    A backup is performed by creating a Backup custom resource. For a tutorial, refer to this page.

    Restoring Rancher​

    A restore is performed by creating a Restore custom resource. For a tutorial, refer to this page.

    Migrating Rancher to a New Cluster​

    A migration is performed by following these steps.

    Default Storage Location Configuration​

    Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible or Minio object store.

    For information on configuring these options, refer to this page.

    Example values.yaml for the rancher-backup Helm Chart​

    The example values.yaml file can be used to configure the rancher-backup operator when the Helm CLI is used to install it.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/backup-restore-configuration.html b/pages-for-subheaders/backup-restore-configuration.html index 32cc46f1335..5cb677db17e 100644 --- a/pages-for-subheaders/backup-restore-configuration.html +++ b/pages-for-subheaders/backup-restore-configuration.html @@ -5,13 +5,13 @@ Rancher Backup Configuration Reference | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/best-practices.html b/pages-for-subheaders/best-practices.html index 2e20d9396d2..2fa25331a78 100644 --- a/pages-for-subheaders/best-practices.html +++ b/pages-for-subheaders/best-practices.html @@ -5,13 +5,13 @@ Best Practices Guide | Rancher Manager - +
    Version: v2.6

    Best Practices Guide

    The purpose of this section is to consolidate best practices for Rancher implementations. This also includes recommendations for related technologies, such as Kubernetes, Docker, containers, and more. The objective is to improve the outcome of a Rancher implementation using the operational experience of Rancher and its customers.

    If you have any questions about how these might apply to your use case, please contact your Customer Success Manager or Support.

    Use the navigation bar on the left to find the current best practices for managing and deploying the Rancher Server.

    For more guidance on best practices, you can consult these resources:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/checklist-for-production-ready-clusters.html b/pages-for-subheaders/checklist-for-production-ready-clusters.html index 64af5d1e62d..e9b36e1ef62 100644 --- a/pages-for-subheaders/checklist-for-production-ready-clusters.html +++ b/pages-for-subheaders/checklist-for-production-ready-clusters.html @@ -5,14 +5,14 @@ Checklist for Production-Ready Clusters | Rancher Manager - +
    Version: v2.6

    Checklist for Production-Ready Clusters

    In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services.

    For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on node requirements.

    This is a shortlist of best practices that we strongly recommend for all production clusters.

    For a full list of all the best practices that we recommend, refer to the best practices section.

    Node Requirements​

    • Make sure your nodes fulfill all of the node requirements, including the port requirements.

    Back up etcd​

    • Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure recurring snapshots of etcd for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.

    Cluster Architecture​

    • Nodes should have one of the following role configurations:
      • etcd
      • controlplane
      • etcd and controlplane
      • worker (the worker role should not be used or added on nodes with the etcd or controlplane role)
    • Have at least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • Assign two or more nodes the controlplane role for master component high availability.
    • Assign two or more nodes the worker role for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    For more information about the number of nodes for each Kubernetes role, refer to the section on recommended architecture.

    Logging and Monitoring​

    • Configure alerts/notifiers for Kubernetes components (System Service).
    • Configure logging for cluster analysis and post-mortems.

    Reliability​

    • Perform load tests on your cluster to verify that its hardware can support your workloads.

    Networking​

    • Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for heartbeat-interval is 500, and the default setting for election-timeout is 5000. These settings for etcd tuning allow etcd to run in most networks (except really high latency networks).
    • Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using Kubernetes Cloud Provider resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/cis-scan-guides.html b/pages-for-subheaders/cis-scan-guides.html index 8ad118d0bd9..de0c00d914a 100644 --- a/pages-for-subheaders/cis-scan-guides.html +++ b/pages-for-subheaders/cis-scan-guides.html @@ -5,13 +5,13 @@ CIS Scan Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/cis-scans.html b/pages-for-subheaders/cis-scans.html index f1f8908665a..edd5ff52aa1 100644 --- a/pages-for-subheaders/cis-scans.html +++ b/pages-for-subheaders/cis-scans.html @@ -5,13 +5,13 @@ CIS Scans | Rancher Manager - +
    Version: v2.6

    CIS Scans

    Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark. The CIS scans can run on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE.

    The rancher-cis-benchmark app leverages kube-bench, an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes Sonobuoy for report aggregation.

    About the CIS Benchmark​

    The Center for Internet Security is a 501(c)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.

    CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.

    The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is

    here.

    About the Generated Report​

    Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.

    By default, the CIS Benchmark v1.6 is used.

    The Benchmark version is included in the generated report.

    The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.

    Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's self-assessment guide for the corresponding Kubernetes version.

    The report contains the following information:

    Column in ReportDescription
    idThe ID number of the CIS Benchmark.
    descriptionThe description of the CIS Benchmark test.
    remediationWhat needs to be fixed in order to pass the test.
    stateIndicates if the test passed, failed, was skipped, or was not applicable.
    node_typeThe node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes.
    auditThis is the audit check that kube-bench runs for this test.
    audit_configAny configuration applicable to the audit script.
    test_infoTest-related info as reported by kube-bench, if any.
    commandsTest-related commands as reported by kube-bench, if any.
    config_commandsTest-related configuration data as reported by kube-bench, if any.
    actual_valueThe test's actual value, present if reported by kube-bench.
    expected_resultThe test's expected result, present if reported by kube-bench.

    Refer to the table in the cluster hardening guide for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.

    Test Profiles​

    The following profiles are available:

    • Generic CIS 1.5
    • Generic CIS 1.6
    • RKE permissive 1.5
    • RKE hardened 1.5
    • RKE permissive 1.6
    • RKE hardened 1.6
    • RKE2 permissive 1.5
    • RKE2 hardened 1.5
    • RKE2 permissive 1.6
    • RKE2 hardened 1.6
    • AKS
    • EKS
    • GKE

    You also have the ability to customize a profile by saving a set of tests to skip.

    All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.

    There are two types of RKE cluster scan profiles:

    • Permissive: This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
    • Hardened: This profile will not skip any tests, except for the non-applicable tests.

    The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.

    In order to pass the "Hardened" profile, you will need to follow the steps on the hardening guide and use the cluster.yml defined in the hardening guide to provision a hardened cluster.

    The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned:

    The rancher-cis-benchmark supports the CIS 1.6 Benchmark version.

    • For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
    • EKS and GKE have their own CIS Benchmarks published by kube-bench. The corresponding test profiles are used by default for those clusters.
    • For RKE2 Kubernetes clusters, the RKE2 Permissive 1.6 profile is the default.
    • For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.

    About Skipped and Not Applicable Tests​

    For a list of skipped and not applicable tests, refer to this page.

    For now, only user-defined skipped tests are marked as skipped in the generated report.

    Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.

    Roles-based Access Control​

    For information about permissions, refer to this page

    Configuration​

    For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to this page

    How-to Guides​

    Please refer here for how-to guides on CIS scans.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/cli-with-rancher.html b/pages-for-subheaders/cli-with-rancher.html index 0184898e5fc..c4e12941c98 100644 --- a/pages-for-subheaders/cli-with-rancher.html +++ b/pages-for-subheaders/cli-with-rancher.html @@ -5,13 +5,13 @@ CLI with Rancher | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/cloud-marketplace.html b/pages-for-subheaders/cloud-marketplace.html index 5df73cd187f..041eaa2c66b 100644 --- a/pages-for-subheaders/cloud-marketplace.html +++ b/pages-for-subheaders/cloud-marketplace.html @@ -5,13 +5,13 @@ Cloud Marketplace Integration | Rancher Manager - +
    Version: v2.6

    Cloud Marketplace Integration

    Rancher offers integration with cloud marketplaces to easily purchase support for installations hosted on certain cloud providers. In addition, this integration also provides the ability to generate a supportconfig bundle which can be provided to rancher support.

    As of Rancher v2.6.7, only AWS is supported for this integration.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/cluster-configuration.html b/pages-for-subheaders/cluster-configuration.html index 7ce38034944..8aa71c06a68 100644 --- a/pages-for-subheaders/cluster-configuration.html +++ b/pages-for-subheaders/cluster-configuration.html @@ -5,13 +5,13 @@ Cluster Configuration | Rancher Manager - +
    Version: v2.6

    Cluster Configuration

    After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster.

    For information on editing cluster membership, go to this page.

    Cluster Configuration References​

    The cluster configuration options depend on the type of Kubernetes cluster:

    Cluster Management Capabilities by Cluster Type​

    The options and settings available for an existing cluster change based on the method that you used to provision it.

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher Launched Kubernetes ClustersEKS, GKE and AKS Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Monitoring, Logging, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/configuration-options.html b/pages-for-subheaders/configuration-options.html index 1afed8d24d2..a0f799e9f0f 100644 --- a/pages-for-subheaders/configuration-options.html +++ b/pages-for-subheaders/configuration-options.html @@ -5,13 +5,13 @@ Configuration Options | Rancher Manager - +
    Version: v2.6

    Configuration Options

    Egress Support​

    By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the overlay file.

    Enabling Automatic Sidecar Injection​

    Automatic sidecar injection is disabled by default. To enable this, set the sidecarInjectorWebhook.enableNamespacesByDefault=true in the values.yaml on install or upgrade. This automatically enables Istio sidecar injection into all new namespaces that are deployed.

    Overlay File​

    An Overlay File is designed to support extensive configuration of your Istio installation. It allows you to make changes to any values available in the IstioOperator API. This will ensure you can customize the default installation to fit any scenario.

    The Overlay File will add configuration on top of the default installation that is provided from the Istio chart installation. This means you do not need to redefine the components that already defined for installation.

    For more information on Overlay Files, refer to the Istio documentation.

    Selectors and Scrape Configs​

    The Monitoring app sets prometheus.prometheusSpec.ignoreNamespaceSelectors=false which enables monitoring across all namespaces by default. This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with istio-injection=enabled label.

    If you would like to limit Prometheus to specific namespaces, set prometheus.prometheusSpec.ignoreNamespaceSelectors=true. Once you do this, you will need to add additional configuration to continue to monitor your resources.

    For details, refer to this section.

    Enable Istio with Pod Security Policies​

    Refer to this section.

    Additional Steps for Installing Istio on an RKE2 Cluster​

    Refer to this section.

    Additional Steps for Project Network Isolation​

    Refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html b/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html index 2ee8ced3801..62c831f92d5 100644 --- a/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html +++ b/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html @@ -5,13 +5,13 @@ Configuring Microsoft Active Directory Federation Service (SAML) | Rancher Manager - +
    Version: v2.6

    Configuring Microsoft Active Directory Federation Service (SAML)

    If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.

    Prerequisites​

    You must have Rancher installed.

    • Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the <RANCHER_SERVER> placeholder.
    • You must have a global administrator account on your Rancher installation.

    You must have a Microsoft AD FS Server configured.

    • Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the <AD_SERVER> placeholder.
    • You must have access to add Relying Party Trusts on your AD FS Server.

    Setup Outline​

    Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    Next: Configuring Microsoft AD FS for Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/configure-openldap.html b/pages-for-subheaders/configure-openldap.html index 10678d91c5f..da3c54f71e9 100644 --- a/pages-for-subheaders/configure-openldap.html +++ b/pages-for-subheaders/configure-openldap.html @@ -5,13 +5,13 @@ Configuring OpenLDAP | Rancher Manager - +
    Version: v2.6

    Configuring OpenLDAP

    If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.

    Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. In the top left corner, click ☰ > Users & Authentication.
    2. In the left navigation menu, click Auth Provider.
    3. Click OpenLDAP. Fill out the Configure an OpenLDAP server form.
    4. Click Enable.

    Test Authentication​

    Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.

    note

    The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step.

    1. Enter the username and password for the OpenLDAP account that should be mapped to the local principal account.
    2. Click Authenticate With OpenLDAP to test the OpenLDAP connection and finalise the setup.

    Result:

    • OpenLDAP authentication is configured.
    • The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account.
    note

    You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/configure-shibboleth-saml.html b/pages-for-subheaders/configure-shibboleth-saml.html index f432da7145e..25810b0ec59 100644 --- a/pages-for-subheaders/configure-shibboleth-saml.html +++ b/pages-for-subheaders/configure-shibboleth-saml.html @@ -5,7 +5,7 @@ Configuring Shibboleth (SAML) | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.6

    Configuring Shibboleth (SAML)

    If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.

    In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.

    The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to this page.

    Setting up Shibboleth in Rancher

    Shibboleth Prerequisites​

    • You must have a Shibboleth IdP Server configured.
    • Following are the Rancher Service Provider URLs needed for configuration: Metadata URL: https://<rancher-server>/v1-saml/shibboleth/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/shibboleth/saml/acs
    • Export a metadata.xml file from your IdP Server. For more information, see the Shibboleth documentation.

    Configure Shibboleth in Rancher​

    If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

    1. In the top left corner, click ☰ > Users & Authentication.

    2. In the left navigation menu, click Auth Provider.

    3. Click Shibboleth.

    4. Complete the Configure Shibboleth Account form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Rancher API Host: Enter the URL for your Rancher Server.

      6. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      7. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Shibboleth Account form, click Enable.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.

      note

      You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.

    SAML Provider Caveats​

    If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.

    • There is no validation on users or groups when assigning permissions to them in Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.

    Setting up OpenLDAP in Rancher

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.

    OpenLDAP Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference. Note that nested group membership is not available for Shibboleth.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. Log into the Rancher UI using the initial local admin account.
    2. In the top left corner, click ☰ > Users & Authentication.
    3. In the left navigation menu, click Auth Provider.
    4. Click OpenLDAP. The Configure an OpenLDAP server form will be displayed.

    Troubleshooting

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/create-kubernetes-persistent-storage.html b/pages-for-subheaders/create-kubernetes-persistent-storage.html index 3035b9f936e..b4e87e62bea 100644 --- a/pages-for-subheaders/create-kubernetes-persistent-storage.html +++ b/pages-for-subheaders/create-kubernetes-persistent-storage.html @@ -5,13 +5,13 @@ Kubernetes Persistent Storage: Volumes and Storage Classes | Rancher Manager - +
    Version: v2.6

    Kubernetes Persistent Storage: Volumes and Storage Classes

    When deploying an application that needs to retain data, you'll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application's pod fails.

    The documents in this section assume that you understand the Kubernetes concepts of persistent volumes, persistent volume claims, and storage classes. For more information, refer to the section on how storage works.

    Prerequisites​

    To set up persistent storage, the Manage Volumes role is required.

    If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    For provisioning new storage with Rancher, the cloud provider must be enabled. For details on enabling cloud providers, refer to this page.

    For attaching existing persistent storage to a cluster, the cloud provider does not need to be enabled.

    Setting up Existing Storage​

    The overall workflow for setting up existing storage is as follows:

    1. Set up your persistent storage. This may be storage in an infrastructure provider, or it could be your own storage.
    2. Add a persistent volume (PV) that refers to the persistent storage.
    3. Add a persistent volume claim (PVC) that refers to the PV.
    4. Mount the PVC as a volume in your workload.

    For details and prerequisites, refer to this page.

    Dynamically Provisioning New Storage in Rancher​

    The overall workflow for provisioning new storage is as follows:

    1. Add a StorageClass and configure it to use your storage provider. The StorageClass could refer to storage in an infrastructure provider, or it could refer to your own storage.
    2. Add a persistent volume claim (PVC) that refers to the storage class.
    3. Mount the PVC as a volume for your workload.

    For details and prerequisites, refer to this page.

    Longhorn Storage​

    Longhorn is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.

    Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI.

    If you have a pool of block storage, Longhorn can help you provide persistent storage to your Kubernetes cluster without relying on cloud providers. For more information about Longhorn features, refer to the documentation.

    Rancher v2.5 simplified the process of installing Longhorn on a Rancher-managed cluster. For more information, see this page.

    Provisioning Storage Examples​

    We provide examples of how to provision storage with NFS, vSphere, and Amazon's EBS.

    GlusterFS Volumes​

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. For details on preventing this from happening, refer to this page.

    iSCSI Volumes​

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. For details on resolving this issue, refer to this page.

    hostPath Volumes​

    Before you create a hostPath volume, you need to set up an extra_bind in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads.

    Migrating vSphere Cloud Provider from In-tree to Out-of-tree​

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    For instructions on how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/custom-resource-configuration.html b/pages-for-subheaders/custom-resource-configuration.html index 5cb60bfbdab..d025dfe9816 100644 --- a/pages-for-subheaders/custom-resource-configuration.html +++ b/pages-for-subheaders/custom-resource-configuration.html @@ -5,13 +5,13 @@ Custom Resource Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/deploy-apps-across-clusters.html b/pages-for-subheaders/deploy-apps-across-clusters.html index fb017f9845e..4007e63b9e0 100644 --- a/pages-for-subheaders/deploy-apps-across-clusters.html +++ b/pages-for-subheaders/deploy-apps-across-clusters.html @@ -5,13 +5,13 @@ Deploying Applications across Clusters | Rancher Manager - +
    Version: v2.6

    Deploying Applications across Clusters

    Fleet​

    Rancher v2.5 introduced Fleet, a new way to deploy applications across clusters.

    Fleet is GitOps at scale. For more information, refer to the Fleet section.

    Multi-cluster Apps​

    In Rancher before v2.5, the multi-cluster apps feature was used to deploy applications across clusters. The multi-cluster apps feature is deprecated, but still available in Rancher v2.5.

    Refer to the documentation here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/deploy-rancher-manager.html b/pages-for-subheaders/deploy-rancher-manager.html index 9574e1d7d43..ab932ef1f45 100644 --- a/pages-for-subheaders/deploy-rancher-manager.html +++ b/pages-for-subheaders/deploy-rancher-manager.html @@ -5,13 +5,13 @@ Deploying Rancher Server | Rancher Manager - +
    Version: v2.6

    Deploying Rancher Server

    Use one of the following guides to deploy and provision Rancher and a Kubernetes cluster in the provider of your choice.

    If you prefer, the following guide will take you through the same process in individual steps. Use this if you want to run Rancher in a different provider, on prem, or if you would just like to see how easy it is.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/deploy-rancher-workloads.html b/pages-for-subheaders/deploy-rancher-workloads.html index bd7d4bdb2f3..441a53a2bf5 100644 --- a/pages-for-subheaders/deploy-rancher-workloads.html +++ b/pages-for-subheaders/deploy-rancher-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/downstream-cluster-configuration.html b/pages-for-subheaders/downstream-cluster-configuration.html index 525032dfd74..6fe081a6e77 100644 --- a/pages-for-subheaders/downstream-cluster-configuration.html +++ b/pages-for-subheaders/downstream-cluster-configuration.html @@ -5,13 +5,13 @@ Downstream Cluster Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/enable-experimental-features.html b/pages-for-subheaders/enable-experimental-features.html index 2adc8084f1c..fa3acb5e689 100644 --- a/pages-for-subheaders/enable-experimental-features.html +++ b/pages-for-subheaders/enable-experimental-features.html @@ -5,13 +5,13 @@ Enabling Experimental Features | Rancher Manager - +
    Version: v2.6

    Enabling Experimental Features

    Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an unsupported storage type outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.

    The features can be enabled in three ways:

    Each feature has two values:

    • A default value, which can be configured with a flag or environment variable from the command line
    • A set value, which can be configured with the Rancher API or UI

    If no value has been set, Rancher uses the default value.

    Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.

    For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the feature flags page for more information.

    Enabling Features when Starting Rancher

    When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.

    Enabling Features for Kubernetes Installs​

    note

    Values set from the Rancher API will override the value passed in through the command line.

    When installing Rancher with a Helm chart, use the --set option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

    helm install rancher rancher-latest/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set 'extraEnv[0].name=CATTLE_FEATURES'
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
    note

    If you are installing an alpha version, Helm requires adding the --devel option to the command.

    Rendering the Helm Chart for Air Gap Installations​

    For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the air gap installation documentation.

    Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.

    The Helm command is as follows:

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
      --no-hooks \ # prevent files for Helm hooks from being generated
      --namespace cattle-system \
      --set hostname=<RANCHER.YOURDOMAIN.COM> \
      --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
      --set ingress.tls.source=secret \
      --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
      --set useBundledSystemChart=true # Use the packaged Rancher system charts
      --set 'extraEnv[0].name=CATTLE_FEATURES'
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'

    Enabling Features for Docker Installs​

    When installing Rancher with Docker, use the --features option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

    docker run -d -p 80:80 -p 443:443 \
      --restart=unless-stopped \
      rancher/rancher:rancher-latest \
      --features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true

    Enabling Features with the Rancher UI

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags.
    3. To enable a feature, go to the disabled feature you want to enable and click ⋮ > Activate.

    Result: The feature is enabled.

    Disabling Features with the Rancher UI​

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags. You will see a list of experimental features.
    3. To disable a feature, go to the enabled feature you want to disable and click ⋮ > Deactivate.

    Result: The feature is disabled.

    Enabling Features with the Rancher API

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click True.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is enabled.

    Disabling Features with the Rancher API​

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click False.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is disabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/fleet-gitops-at-scale.html b/pages-for-subheaders/fleet-gitops-at-scale.html index cc759764cbf..196c9b7ad17 100644 --- a/pages-for-subheaders/fleet-gitops-at-scale.html +++ b/pages-for-subheaders/fleet-gitops-at-scale.html @@ -5,13 +5,13 @@ Fleet - GitOps at Scale | Rancher Manager - +
    Version: v2.6

    Fleet - GitOps at Scale

    Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It’s also lightweight enough that it works great for a single cluster too, but it really shines when you get to a large scale. By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.

    Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.

    Architecture​

    For information about how Fleet works, see this page.

    Accessing Fleet in the Rancher UI​

    Fleet comes preinstalled in Rancher and is managed by the Continuous Delivery option in the Rancher UI. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer here.

    Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following gitops practice.

    Follow the steps below to access Continuous Delivery in the Rancher UI:

    1. Click ☰ > Continous Delivery.

    2. Select your namespace at the top of the menu, noting the following:

      • By default, fleet-default is selected which includes all downstream clusters that are registered through Rancher.

      • You may switch to fleet-local, which only contains the local cluster, or you may create your own workspace to which you may assign and move clusters.

      • You can then manage clusters by clicking on Clusters on the left navigation bar.

    3. Click on Gitrepos on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.

    4. Select your git repository and target clusters/cluster group. You can also create the cluster group in the UI by clicking on Cluster Groups from the left navigation bar.

    5. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.

    Windows Support​

    For details on support for clusters with Windows nodes, see this page.

    GitHub Repository​

    The Fleet Helm charts are available here.

    Using Fleet Behind a Proxy​

    For details on using Fleet behind a proxy, see this page.

    Helm Chart Dependencies​

    In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run helm install, your installation will fail because the dependencies will be missing.

    The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run helm dependencies update $chart OR run helm dependencies build $chart locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters

    Troubleshooting​

    • Known Issue: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs here.

    Documentation​

    The Fleet documentation is at https://fleet.rancher.io/.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/gke-cluster-configuration.html b/pages-for-subheaders/gke-cluster-configuration.html index 51bd3142d92..febdf44a954 100644 --- a/pages-for-subheaders/gke-cluster-configuration.html +++ b/pages-for-subheaders/gke-cluster-configuration.html @@ -5,13 +5,13 @@ GKE Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    GKE Cluster Configuration Reference

    Changes in Rancher v2.6​

    • Support for additional configuration options:
      • Project network isolation
      • Network tags

    Cluster Location​

    ValueDescription
    Location TypeZonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to these docs.
    ZoneEach region in Compute engine contains a number of zones. For more information about available regions and zones, refer to these docs.
    Additional ZonesFor zonal clusters, you can select additional zones to create a multi-zone cluster.
    RegionFor regional clusters, you can select a region. For more information about available regions and zones, refer to this section. The first part of each zone name is the name of the region.

    Cluster Options​

    Kubernetes Version​

    Mutable: yes

    For more information on GKE Kubernetes versions, refer to these docs.

    Container Address Range​

    Mutable: no

    The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster.

    Network​

    Mutable: no

    The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using Shared VPCs, the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to this page.

    Node Subnet / Subnet​

    Mutable: no

    The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the Network field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, Subnetwork Name is required to generate one. If using Shared VPCs, the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to this page.

    Subnetwork Name​

    Mutable: no

    Automatically create a subnetwork with the provided name. Required if "Auto Create Subnetwork" is selected for Node Subnet or Subnet. For more information on subnetworks, refer to this page.

    Ip Aliases​

    Mutable: no

    Enable alias IPs. This enables VPC-native traffic routing. Required if using Shared VPCs.

    Network Policy​

    Mutable: yes

    Enable network policy enforcement on the cluster. A network policy defines the level of communication that can occur between pods and services in the cluster. For more information, refer to this page.

    Project Network Isolation​

    Mutable: yes

    choose whether to enable or disable inter-project communication. Note that enabling Project Network Isolation will automatically enable Network Policy and Network Policy Config, but not vice versa.

    Node Ipv4 CIDR Block​

    Mutable: no

    The IP address range of the instance IPs in this cluster. Can be set if "Auto Create Subnetwork" is selected for Node Subnet or Subnet. Must be a valid CIDR range, e.g. 10.96.0.0/14. For more information on how to determine the IP address range, refer to this page.

    Cluster Secondary Range Name​

    Mutable: no

    The name of an existing secondary range for Pod IP addresses. If selected, Cluster Pod Address Range will automatically be populated. Required if using a Shared VPC network.

    Cluster Pod Address Range​

    Mutable: no

    The IP address range assigned to pods in the cluster. Must be a valid CIDR range, e.g. 10.96.0.0/11. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your pods, refer to this section.

    Services Secondary Range Name​

    Mutable: no

    The name of an existing secondary range for service IP addresses. If selected, Service Address Range will be automatically populated. Required if using a Shared VPC network.

    Service Address Range​

    Mutable: no

    The address range assigned to the services in the cluster. Must be a valid CIDR range, e.g. 10.94.0.0/18. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your services, refer to this section.

    Private Cluster​

    Mutable: no

    caution

    Private clusters require additional planning and configuration outside of Rancher. Refer to the private cluster guide.

    Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP.

    Enable Private Endpoint​

    caution

    Private clusters require additional planning and configuration outside of Rancher. Refer to the private cluster guide.

    Mutable: no

    Locks down external access to the control plane endpoint. Only available if Private Cluster is also selected. If selected, and if Rancher does not have direct access to the Virtual Private Cloud network the cluster is running in, Rancher will provide a registration command to run on the cluster to enable Rancher to connect to it.

    Master IPV4 CIDR Block​

    Mutable: no

    The IP range for the control plane VPC.

    Master Authorized Network​

    Mutable: yes

    Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required.

    Additional Options

    Cluster Addons​

    Additional Kubernetes cluster components. For more information, refer to this page.

    Horizontal Pod Autoscaling​

    Mutable: yes

    The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see this page.

    HTTP (L7) Load Balancing​

    Mutable: yes

    HTTP (L7) Load Balancing distributes HTTP and HTTPS traffic to backends hosted on GKE. For more information, refer to this page.

    Network Policy Config (master only)​

    Mutable: yes

    Configuration for NetworkPolicy. This only tracks whether the addon is enabled or not on the master, it does not track whether network policy is enabled for the nodes.

    Cluster Features (Alpha Features)​

    Mutable: no

    Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to this page.

    Logging Service​

    Mutable: yes

    The logging service the cluster uses to write logs. Use either Cloud Logging or no logging service in which case no logs are exported from the cluster.

    Monitoring Service​

    Mutable: yes

    The monitoring service the cluster uses to write metrics. Use either Cloud Monitoring or monitoring service in which case no metrics are exported from the cluster.

    Maintenance Window​

    Mutable: yes

    Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to this page.

    Node Pools

    In this section, enter details describing the configuration of each node in the node pool.

    Kubernetes Version​

    Mutable: yes

    The Kubernetes version for each node in the node pool. For more information on GKE Kubernetes versions, refer to these docs.

    Image Type​

    Mutable: yes

    The node operating system image. For more information for the node image options that GKE offers for each OS, refer to this page.

    note

    The default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the legacy logging implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The current logging feature is compatible with the Container-Optimized OS image.

    note

    If selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool.

    Machine Type​

    Mutable: no

    The virtualized hardware resources available to node instances. For more information on Google Cloud machine types, refer to this page.

    Root Disk Type​

    Mutable: no

    Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to this section.

    Local SSD Disks​

    Mutable: no

    Configure each node's local SSD disk storage in GB. Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see this section.

    Preemptible nodes (beta)​

    Mutable: no

    Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see this page.

    Taints​

    Mutable: no

    When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool.

    Node Labels​

    Mutable: no

    You can apply labels to the node pool, which applies the labels to all nodes in the pool.

    Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.

    Network Tags​

    Mutable: no

    You can add network tags to the node pool to make firewall rules and routes between subnets. Tags will apply to all nodes in the pool.

    For details on tag syntax and requirements, see the Kubernetes documentation.

    Group Details

    In this section, enter details describing the node pool.

    Name​

    Mutable: no

    Enter a name for the node pool.

    Initial Node Count​

    Mutable: yes

    Integer for the starting number of nodes in the node pool.

    Max Pod Per Node​

    Mutable: no

    GKE has a hard limit of 110 Pods per node. For more information on the Kubernetes limits, see this section.

    Autoscaling​

    Mutable: yes

    Node pool autoscaling dynamically creates or deletes nodes based on the demands of your workload. For more information, see this page.

    Auto Repair​

    Mutable: yes

    GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on auto-repairing nodes.

    Auto Upgrade​

    Mutable: yes

    When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is updated on your behalf. For more information about auto-upgrading nodes, see this page.

    Access Scopes​

    Mutable: no

    Access scopes are the legacy method of specifying permissions for your nodes.

    • Allow default access: The default access for new clusters is the Compute Engine default service account.
    • Allow full access to all Cloud APIs: Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance.
    • Set access for each API: Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call.

    For more information, see the section about enabling service accounts for a VM.

    Configuring the Refresh Interval​

    The refresh interval can be configured through the setting "gke-refresh", which is an integer representing seconds.

    The default value is 300 seconds.

    The syncing interval can be changed by running kubectl edit setting gke-refresh.

    The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for GCP APIs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/helm-charts-in-rancher.html b/pages-for-subheaders/helm-charts-in-rancher.html index 9a17cbf3724..475dfa9f135 100644 --- a/pages-for-subheaders/helm-charts-in-rancher.html +++ b/pages-for-subheaders/helm-charts-in-rancher.html @@ -5,13 +5,13 @@ Helm Charts in Rancher | Rancher Manager - +
    Version: v2.6

    Helm Charts in Rancher

    In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using Apps & Marketplace. It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster.

    Changes in Rancher v2.6​

    Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts was implemented. The changes are centered around the major version of the charts and the +up annotation for upstream charts, where applicable.

    Major Version: The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your Apps & Marketplace charts are also upgraded to the correct release line for the chart.

    note

    Any major versions that are less than the ones mentioned in the table below are meant for 2.5 and below only. For example, you are advised to not use <100.x.x versions of Monitoring in 2.6.x+.

    Feature Charts:

    NameSupported Minimum VersionSupported Maximum Version
    external-ip-webhook100.0.0+up1.0.0100.0.1+up1.0.1
    harvester-cloud-provider100.0.2+up0.1.12100.0.2+up0.1.12
    harvester-csi-driver100.0.2+up0.1.11100.0.2+up0.1.11
    neuvector100.0.0+up2.2.0100.0.0+up2.2.0
    rancher-alerting-drivers100.0.0100.0.2
    rancher-backup2.0.12.1.2
    rancher-cis-benchmark2.0.12.0.4
    rancher-gatekeeper100.0.0+up3.6.0100.1.0+up3.7.1
    rancher-istio100.0.0+up1.10.4100.3.0+up1.13.3
    rancher-logging100.0.0+up3.12.0100.1.2+up3.17.4
    rancher-longhorn100.0.0+up1.1.2100.1.2+up1.2.4
    rancher-monitoring100.0.0+up16.6.0100.1.2+up19.0.3
    rancher-sriov (experimental)100.0.0+up0.1.0100.0.3+up0.1.0
    rancher-vsphere-cpi100.3.0+up1.2.1100.3.0+up1.2.1
    rancher-vsphere-csi100.3.0+up2.5.1-rancher1100.3.0+up2.5.1-rancher1
    rancher-wins-upgrader0.0.100100.0.1+up0.0.1

    **Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also.

    • As an example, 100.x.x+up16.6.0 for Monitoring tracks upstream kube-prometheus-stack 16.6.0 with some Rancher patches added to it.

    • On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > 16.6.0 in Rancher 2.5, you should not upgrade to 100.x.x+up16.6.0. Instead, you should upgrade to the appropriate version in the next release.

    Charts​

    From the top-left menu select "Apps & Marketplace" and you will be taken to the Charts page.

    The charts page contains all Rancher, Partner, and Custom Charts.

    • Rancher tools such as Logging or Monitoring are included under the Rancher label
    • Partner charts reside under the Partners label
    • Custom charts will show up under the name of the repository

    All three types are deployed and managed in the same way.

    note

    Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) should continue to be managed only by the Cluster Manager, and apps managed with Apps & Marketplace in the new UI must be managed only by Apps & Marketplace.

    Repositories​

    From the left sidebar select "Repositories".

    These items represent helm repositories, and can be either traditional helm endpoints which have an index.yaml, or git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository.

    To add a private CA for Helm Chart repositories:

    • HTTP-based chart repositories: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as openssl x509 -outform der -in ca.pem | base64 -w0. Click Edit YAML for the chart repo and set, as in the following example:
      [...]
      spec:
        caBundle:
      MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
      ...
      nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
      [...]
    • Git-based chart repositories: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as openssl x509 -outform der -in ca.pem | base64 -w0. Click Edit YAML for the chart repo and set, as in the following example:
      [...]
      spec:
        caBundle:
      MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
      ...
      nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
      [...]
    Helm chart repositories with authentication

    As of Rancher v2.6.3, a new value disableSameOriginCheck has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL.

    To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the spec portion of the YAML file, add disableSameOriginCheck and set it to true.

    [...]
    spec:
      disableSameOriginCheck: true
    [...]

    Helm Compatibility​

    Only Helm 3 compatible charts are supported.

    Deployment and Upgrades​

    From the "Charts" tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed.

    To view all recent changes, go to the "Recent Operations" tab. From there you can view the call that was made, conditions, events, and logs.

    After installing a chart, you can find it in the "Installed Apps" tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation.

    Most Rancher tools have additional pages located in the toolbar below the "Apps & Marketplace" section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information.

    caution

    If you are upgrading your chart using "Customize Helm options before upgrade" , please be aware that using the "--force" option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can:

    • use the default upgrade option ( i.e do not use "--force" option )
    • uninstall the existing chart and install the upgraded chart
    • delete the resources with immutable fields from the cluster before performing the "--force" upgrade

    Changes in Rancher v2.6.3​

    The upgrade button has been removed for legacy apps from the Apps & Marketplace > Installed Apps page.

    If you have a legacy app installed and want to upgrade it:

    • The legacy feature flag must be turned on (if it's not turned on automatically because of having a legacy app before upgrading)
    • You can upgrade the app from cluster explorer, from the left nav section Legacy > Project > Apps
    • For multi-cluster apps, you can go to ≡ > Multi-cluster Apps and upgrade the app from there

    Limitations​

    Dashboard apps or Rancher feature charts cannot be installed using the Rancher CLI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/horizontal-pod-autoscaler.html b/pages-for-subheaders/horizontal-pod-autoscaler.html index d370d0501c2..e32ad2e942b 100644 --- a/pages-for-subheaders/horizontal-pod-autoscaler.html +++ b/pages-for-subheaders/horizontal-pod-autoscaler.html @@ -5,13 +5,13 @@ The Horizontal Pod Autoscaler | Rancher Manager - +
    Version: v2.6

    The Horizontal Pod Autoscaler

    The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down.

    Rancher provides some additional features to help manage HPAs, depending on the version of Rancher.

    You can create, manage, and delete HPAs using the Rancher UI. It only supports HPA in the autoscaling/v2beta2 API.

    Managing HPAs​

    The way that you manage HPAs is different based on your version of the Kubernetes API:

    • For Kubernetes API version autoscaling/V2beta1: This version of the Kubernetes API lets you autoscale your pods based on the CPU and memory utilization of your application.
    • For Kubernetes API Version autoscaling/V2beta2: This version of the Kubernetes API lets you autoscale your pods based on CPU and memory utilization, in addition to custom metrics.

    You can create, manage, and delete HPAs using the Rancher UI. From the Rancher UI you can configure the HPA to scale based on CPU and memory utilization. For more information, refer to Managing HPAs with the Rancher UI. To scale the HPA based on custom metrics, you still need to use kubectl. For more information, refer to Configuring HPA to Scale Using Custom Metrics with Prometheus.

    Clusters created in Rancher v2.0.7 and higher automatically have all the requirements needed (metrics-server and Kubernetes cluster configuration) to use HPA.

    Testing HPAs with a Service Deployment​

    You can see your HPA's current number of replicas by going to your project and clicking Resources > HPA. For more information, refer to Get HPA Metrics and Status.

    You can also use kubectl to get the status of HPAs that you test with your load testing tool. For more information, refer to Testing HPAs with kubectl.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/infrastructure-setup.html b/pages-for-subheaders/infrastructure-setup.html index 488d4d1c9ca..b69c1144bd4 100644 --- a/pages-for-subheaders/infrastructure-setup.html +++ b/pages-for-subheaders/infrastructure-setup.html @@ -5,13 +5,13 @@ Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
    Version: v2.6

    Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials.

    To set up infrastructure for a high-availability K3s Kubernetes cluster with an external DB, refer to this page.

    To set up infrastructure for a high-availability RKE Kubernetes cluster, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/install-cluster-autoscaler.html b/pages-for-subheaders/install-cluster-autoscaler.html index a82533e6552..f5238d6556c 100644 --- a/pages-for-subheaders/install-cluster-autoscaler.html +++ b/pages-for-subheaders/install-cluster-autoscaler.html @@ -5,13 +5,13 @@ Cluster Autoscaler | Rancher Manager - +
    Version: v2.6

    Cluster Autoscaler

    In this section, you'll learn how to install and use the Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

    The cluster autoscaler is a tool that automatically adjusts the size of the Kubernetes cluster when one of the following conditions is true:

    • There are pods that failed to run in the cluster due to insufficient resources.
    • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes.

    To prevent your pod from being evicted, set a priorityClassName: system-cluster-critical property on your pod spec.

    Cluster Autoscaler is designed to run on Kubernetes master nodes. It can run in the kube-system namespace. Cluster Autoscaler doesn't scale down nodes with non-mirrored kube-system pods running on them.

    It's possible to run a customized deployment of Cluster Autoscaler on worker nodes, but extra care needs to be taken to ensure that Cluster Autoscaler remains up and running.

    Cloud Providers

    Cluster Autoscaler provides support to distinct cloud providers. For more information, go to cluster-autoscaler supported cloud providers.

    Setting up Cluster Autoscaler on Amazon Cloud Provider​

    For details on running the cluster autoscaler on Amazon cloud provider, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html b/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html index 6031111127c..0150f65f96e 100644 --- a/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html +++ b/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html @@ -5,13 +5,13 @@ Install/Upgrade Rancher on a Kubernetes Cluster | Rancher Manager - +
    Version: v2.6

    Install/Upgrade Rancher on a Kubernetes Cluster

    In this section, you'll learn how to deploy Rancher on a Kubernetes cluster using the Helm CLI.

    Prerequisites

    Kubernetes Cluster​

    Set up the Rancher server's local Kubernetes cluster.

    Rancher can be installed on any Kubernetes cluster. This cluster can use upstream Kubernetes, or it can use one of Rancher's Kubernetes distributions, or it can be a managed Kubernetes cluster from a provider such as Amazon EKS.

    For help setting up a Kubernetes cluster, we provide these tutorials:

    • RKE: For the tutorial to install an RKE Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE cluster, refer to this page.
    • K3s: For the tutorial to install a K3s Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability K3s cluster, refer to this page.
    • RKE2: For the tutorial to install an RKE2 Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE2 cluster, refer to this page.
    • Amazon EKS: For details on how to install Rancher on Amazon EKS, including how to install an Ingress controller so that the Rancher server can be accessed, refer to this page.
    • AKS: For details on how to install Rancher with Azure Kubernetes Service, including how to install an Ingress controller so that the Rancher server can be accessed, refer to this page.
    • GKE: For details on how to install Rancher with Google Kubernetes Engine, including how to install an Ingress controller so that the Rancher server can be accessed, refer to this page.

    Ingress Controller​

    The Rancher UI and API are exposed through an Ingress. This means the Kubernetes cluster that you install Rancher in must contain an Ingress controller.

    For RKE, RKE2, and K3s installations, you don't have to install the Ingress controller manually because one is installed by default.

    For distributions that do not include an Ingress Controller by default, like a hosted Kubernetes cluster such as EKS, GKE, or AKS, you have to deploy an Ingress controller first. Note that the Rancher Helm chart does not set an ingressClassName on the ingress by default. Because of this, you have to configure the Ingress controller to also watch ingresses without an ingressClassName.

    Examples are included in the Amazon EKS, AKS, and GKE tutorials above.

    CLI Tools​

    The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your $PATH.

    Install the Rancher Helm Chart

    Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm, we can create configurable deployments instead of just using static files.

    For systems without direct internet access, see Air Gap: Kubernetes install.

    To choose a Rancher version to install, refer to Choosing a Rancher Version.

    To choose a version of Helm to install Rancher with, refer to the Helm version requirements

    note

    The installation instructions assume you are using Helm 3.

    To set up Rancher,

    1. Add the Helm chart repository
    2. Create a namespace for Rancher
    3. Choose your SSL configuration
    4. Install cert-manager (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
    5. Install Rancher with Helm and your chosen certificate option
    6. Verify that the Rancher server is successfully deployed
    7. Save your options

    1. Add the Helm Chart Repository​

    Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-alpha https://releases.rancher.com/server-charts/alpha
      Note: Upgrades are not supported to, from, or between Alphas.

    2. Create a Namespace for Rancher​

    We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system:

    kubectl create namespace cattle-system

    3. Choose your SSL Configuration​

    The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.

    note

    If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

    There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:

    • Rancher-generated TLS certificate: In this case, you will need to install cert-manager into the cluster. Rancher utilizes cert-manager to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. cert-manager is then responsible for managing that certificate.
    • Let's Encrypt: The Let's Encrypt option also uses cert-manager. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (HTTP-01), so the load balancer must have a public DNS record and be accessible from the internet.
    • Bring your own certificate: This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name tls.crt and tls.key. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
    ConfigurationHelm Chart OptionRequires cert-manager
    Rancher Generated Certificates (Default)ingress.tls.source=rancheryes
    Let’s Encryptingress.tls.source=letsEncryptyes
    Certificates from Filesingress.tls.source=secretno

    4. Install cert-manager​

    note

    New in v2.6.4, cert-manager versions 1.6.2 and 1.7.1 are compatible. We recommend v1.7.x because v 1.6.x will reach end-of-life on March 30, 2022.

    You should skip this step if you are bringing your own certificate files (option ingress.tls.source=secret), or if you use TLS termination on an external load balancer.

    This step is only required to use certificates issued by Rancher's generated CA (ingress.tls.source=rancher) or to request Let's Encrypt issued certificates (ingress.tls.source=letsEncrypt).

    Click to Expand
    Important:

    Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade documentation.

    These instructions are adapted from the official cert-manager documentation.

    # If you have installed the CRDs manually instead of with the `--set installCRDs=true` option added to your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart:
    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.7.1/cert-manager.crds.yaml

    # Add the Jetstack Helm repository
    helm repo add jetstack https://charts.jetstack.io

    # Update your local Helm chart repository cache
    helm repo update

    # Install the cert-manager Helm chart
    helm install cert-manager jetstack/cert-manager \
      --namespace cert-manager \
      --create-namespace \
      --version v1.7.1

    Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

    kubectl get pods --namespace cert-manager

    NAME                                       READY   STATUS    RESTARTS   AGE
    cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
    cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
    cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

    5. Install Rancher with Helm and Your Chosen Certificate Option​

    The exact command to install Rancher differs depending on the certificate configuration.

    However, irrespective of the certificate configuration, the name of the Rancher installation in the cattle-system namespace should always be rancher.

    Testing and Development:

    This final command to install Rancher requires a domain name that forwards traffic to Rancher. If you are using the Helm CLI to set up a proof-of-concept, you can use a fake domain name when passing the hostname option. An example of a fake domain name would be <IP_OF_LINUX_NODE>.sslip.io, which would expose Rancher on an IP where it is running. Production installs would require a real domain name.

    The default is for Rancher to generate a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.

    Because rancher is the default option for ingress.tls.source, we are not specifying ingress.tls.source when running the helm install command.

    • Set the hostname to the DNS name you pointed at your load balancer.
    • Set the bootstrapPassword to something unique for the admin user.
    • To install a specific Rancher version, use the --version flag, example: --version 2.3.6
    helm install rancher rancher-<CHART_REPO>/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set bootstrapPassword=admin

    If you are installing an alpha version, Helm requires adding the --devel option to the install command:

    helm install rancher rancher-alpha/rancher --devel

    Wait for Rancher to be rolled out:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.

    See the Chart Options for the full list of options.

    6. Verify that the Rancher Server is Successfully Deployed​

    After adding the secrets, check if Rancher was rolled out successfully:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    If you see the following error: error: deployment "rancher" exceeded its progress deadline, you can check the status of the deployment by running the following command:

    kubectl -n cattle-system get deploy rancher
    NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    rancher   3         3         3            3           3m

    It should show the same count for DESIRED and AVAILABLE.

    7. Save Your Options​

    Make sure you save the --set options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.

    Finishing Up​

    That's it. You should have a functional Rancher server.

    In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.

    Doesn't work? Take a look at the Troubleshooting Page

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/installation-and-upgrade.html b/pages-for-subheaders/installation-and-upgrade.html index 729388009a3..ad4a2ba6335 100644 --- a/pages-for-subheaders/installation-and-upgrade.html +++ b/pages-for-subheaders/installation-and-upgrade.html @@ -5,13 +5,13 @@ Installing/Upgrading Rancher | Rancher Manager - +
    Version: v2.6

    Installing/Upgrading Rancher

    This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.

    Terminology

    In this section,

    • The Rancher server manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface. The Rancher management server can be installed on any Kubernetes cluster, including hosted clusters, such as Amazon EKS clusters.
    • RKE (Rancher Kubernetes Engine) is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster.
    • K3s (Lightweight Kubernetes) is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB.
    • RKE2 is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.

    Note the restrictedAdmin Helm chart option available for the Rancher Server. When this option is set to true, the initial Rancher user has restricted access to the local Kubernetes cluster to prevent privilege escalation. For more information, see the section about the restricted-admin role.

    Overview of Installation Options

    Rancher can be installed on these main architectures:

    High-availability Kubernetes Install with the Helm CLI​

    We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required.

    Automated Quickstart to Deploy Rancher on Amazon EKS​

    Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS Kubernetes cluster following AWS best practices. The deployment guide is here.

    Single-node Kubernetes Install​

    Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't have high availability, which is important for running Rancher in production.

    However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server.

    Docker Install​

    For test and demonstration purposes, Rancher can be installed with Docker on a single node. A local Kubernetes cluster is installed in the single Docker container, and Rancher is installed on the local cluster.

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Other Options​

    There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy:

    Level of Internet AccessKubernetes Installation - Strongly RecommendedDocker Installation
    With direct access to the InternetDocsDocs
    Behind an HTTP proxyDocsThese docs, plus this configuration
    In an air gap environmentDocsDocs

    We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage.

    For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters.

    For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only.

    Our instructions for installing Rancher on Kubernetes describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster.

    When the nodes in your Kubernetes cluster are running and fulfill the node requirements, you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster.

    For a longer discussion of Rancher architecture, refer to the architecture overview, recommendations for production-grade architecture, or our best practices guide.

    Prerequisites

    Before installing Rancher, make sure that your nodes fulfill all of the installation requirements.

    Architecture Tip

    For the best performance and greater security, we recommend a separate, dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    For more architecture recommendations, refer to this page.

    More Options for Installations on a Kubernetes Cluster​

    Refer to the Helm chart options for details on installing Rancher on a Kubernetes cluster with other configurations, including:

    In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation:

    More Options for Installations with Docker​

    Refer to the docs about options for Docker installs for details about other configurations including:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/installation-references.html b/pages-for-subheaders/installation-references.html index a9512f9499b..0b7c1258dbb 100644 --- a/pages-for-subheaders/installation-references.html +++ b/pages-for-subheaders/installation-references.html @@ -5,13 +5,13 @@ Installation References | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/installation-requirements.html b/pages-for-subheaders/installation-requirements.html index 76e86cd9735..e3c76884de0 100644 --- a/pages-for-subheaders/installation-requirements.html +++ b/pages-for-subheaders/installation-requirements.html @@ -5,13 +5,13 @@ Installation Requirements | Rancher Manager - +
    Version: v2.6

    Installation Requirements

    This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.

    Important:

    If you install Rancher on a Kubernetes cluster, requirements are different from the node requirements for downstream user clusters, which will run your apps and services.

    Make sure the node(s) for the Rancher server fulfill the following requirements:

    For a list of best practices that we recommend for running the Rancher server in production, refer to the best practices section.

    The Rancher UI works best in Firefox or Chromium based browsers (Chrome, Edge, Opera, Brave, ...).

    Operating Systems and Container Runtime Requirements

    Rancher should work with any modern Linux distribution.

    Docker is required for nodes that will run RKE Kubernetes clusters. It is not required for RKE2 or K3s clusters.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms.

    For details on which OS and Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    All supported operating systems are 64-bit x86.

    The ntp (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.

    Some distributions of Linux may have default firewall rules that block communication within the Kubernetes cluster. Since Kubernetes v1.19, firewalld must be turned off, because it conflicts with the Kubernetes networking plugins.

    If you don't feel comfortable doing so, you might check suggestions in the respective issue. Some users were successful creating a separate firewalld zone with a policy of ACCEPT for the Pod CIDR.

    If you plan to run Rancher on ARM64, see Running on ARM64 (Experimental).

    RKE Specific Requirements​

    For the container runtime, RKE should work with any modern Docker version.

    For more information see Installing Docker,

    K3s Specific Requirements​

    For the container runtime, K3s bundles its own containerd by default. Alternatively, you can configure K3s to use an already installed Docker runtime. For more information on using K3s with Docker see the K3s documentation.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

    If you are installing Rancher on a K3s cluster with Raspbian Buster, follow these steps to switch to legacy iptables.

    If you are installing Rancher on a K3s cluster with Alpine Linux, follow these steps for additional setup.

    RKE2 Specific Requirements​

    For the container runtime, RKE2 bundles its own containerd. Docker is not required for RKE2 installs.

    For details on which OS versions were tested with RKE2, refer to the support maintenance terms.

    Hardware Requirements

    The following sections describe the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.

    CPU and Memory

    Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.

    RKE and Hosted Kubernetes​

    These CPU and memory requirements apply to each host in the Kubernetes cluster where the Rancher server is installed.

    These requirements apply to RKE Kubernetes clusters, as well as to hosted Kubernetes clusters such as EKS.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 150Up to 150028 GB
    MediumUp to 300Up to 3000416 GB
    LargeUp to 500Up to 5000832 GB
    X-LargeUp to 1000Up to 10,0001664 GB
    XX-LargeUp to 2000Up to 20,00032128 GB

    Every use case and environment is different. Please contact Rancher to review yours.

    K3s Kubernetes​

    These CPU and memory requirements apply to each host in a K3s Kubernetes cluster where the Rancher server is installed.

    Deployment SizeClustersNodesvCPUsRAMDatabase Size
    SmallUp to 150Up to 150028 GB2 cores, 4 GB + 1000 IOPS
    MediumUp to 300Up to 3000416 GB2 cores, 4 GB + 1000 IOPS
    LargeUp to 500Up to 5000832 GB2 cores, 4 GB + 1000 IOPS
    X-LargeUp to 1000Up to 10,0001664 GB2 cores, 4 GB + 1000 IOPS
    XX-LargeUp to 2000Up to 20,00032128 GB2 cores, 4 GB + 1000 IOPS

    Every use case and environment is different. Please contact Rancher to review yours.

    RKE2 Kubernetes​

    These CPU and memory requirements apply to each instance with RKE2 installed. Minimum recommendations are outlined here.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 5Up to 5025 GB
    MediumUp to 15Up to 20039 GB

    Docker​

    These CPU and memory requirements apply to a host with a single-node installation of Rancher.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 5Up to 5014 GB
    MediumUp to 15Up to 20028 GB

    Ingress

    Each node in the Kubernetes cluster that Rancher is installed on should run an Ingress.

    The Ingress should be deployed as DaemonSet to ensure your load balancer can successfully route traffic to all nodes.

    For RKE, RKE2 and K3s installations, you don't have to install the Ingress manually because it is installed by default.

    For hosted Kubernetes clusters (EKS, GKE, AKS), you will need to set up the ingress.

    • Amazon EKS: For details on how to install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to this page.
    • AKS: For details on how to install Rancher with Azure Kubernetes Service, including how to install an ingress so that the Rancher server can be accessed, refer to this page.
    • GKE: For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to this page.

    Disks

    Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.

    Networking Requirements

    This section describes the networking requirements for the node(s) where the Rancher server is installed.

    caution

    If a server containing Rancher has the X-Frame-Options=DENY header, some pages in the new Rancher UI will not be able to render after upgrading from the legacy UI. This is because some legacy pages are embedded as iFrames in the new UI.

    Node IP Addresses​

    Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    Port Requirements​

    To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. Port Requirements lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.

    Dockershim Support

    For more information on Dockershim support, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/integrations-in-rancher.html b/pages-for-subheaders/integrations-in-rancher.html index 01d60c38e64..bcb0ee0b77b 100644 --- a/pages-for-subheaders/integrations-in-rancher.html +++ b/pages-for-subheaders/integrations-in-rancher.html @@ -5,13 +5,13 @@ Integrations in Rancher | Rancher Manager - +
    Version: v2.6

    Integrations in Rancher

    Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI.

    Examples of some of these integrations are Harvester and NeuVector.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/introduction.html b/pages-for-subheaders/introduction.html index 822952c6910..b17d51cc207 100644 --- a/pages-for-subheaders/introduction.html +++ b/pages-for-subheaders/introduction.html @@ -5,13 +5,13 @@ Introduction | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/istio-setup-guide.html b/pages-for-subheaders/istio-setup-guide.html index ea2413dc857..509e5f45cea 100644 --- a/pages-for-subheaders/istio-setup-guide.html +++ b/pages-for-subheaders/istio-setup-guide.html @@ -5,13 +5,13 @@ Setup Guide | Rancher Manager - +
    Version: v2.6

    Setup Guide

    This section describes how to enable Istio and start using it in your projects.

    If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.

    Prerequisites

    This guide assumes you have already installed Rancher, and you have already provisioned a separate Kubernetes cluster on which you will install Istio.

    The nodes in your cluster must meet the CPU and memory requirements.

    The workloads and services that you want to be controlled by Istio must meet Istio's requirements.

    Install

    Quick Setup Tip:

    If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for setting up the Istio gateway and setting up Istio's components for traffic management.

    1. Enable Istio in the cluster.
    2. Enable Istio in all the namespaces where you want to use it.
    3. Add deployments and services that have the Istio sidecar injected.
    4. Set up the Istio gateway.
    5. Set up Istio's components for traffic management.
    6. Generate traffic and see Istio in action.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/istio.html b/pages-for-subheaders/istio.html index b1378f89944..b9b5ef23866 100644 --- a/pages-for-subheaders/istio.html +++ b/pages-for-subheaders/istio.html @@ -5,13 +5,13 @@ Istio | Rancher Manager - +
    Version: v2.6

    Istio

    Istio is an open-source tool that makes it easier for DevOps teams to observe, secure, control, and troubleshoot the traffic within a complex network of microservices.

    As a network of microservices changes and grows, the interactions between them can become increasingly difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.

    Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to a team of developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

    This core service mesh provides features that include but are not limited to the following:

    • Traffic Management such as ingress and egress routing, circuit breaking, mirroring.
    • Security with resources to authenticate and authorize traffic and users, mTLS included.
    • Observability of logs, metrics, and distributed traffic flows.

    After setting up istio you can leverage Istio's control plane functionality through the Rancher UI, kubectl, or istioctl.

    Istio needs to be set up by a cluster-admin before it can be used in a project.

    What's New in Rancher v2.5​

    The overall architecture of Istio has been simplified. A single component, Istiod, has been created by combining Pilot, Citadel, Galley and the sidecar injector. Node Agent functionality has also been merged into istio-agent.

    Addons that were previously installed by Istio (cert-manager, Grafana, Jaeger, Kiali, Prometheus, Zipkin) will now need to be installed separately. Istio will support installation of integrations that are from the Istio Project and will maintain compatibility with those that are not.

    A Prometheus integration will still be available through an installation of Rancher Monitoring, or by installing your own Prometheus operator. Rancher's Istio chart will also install Kiali by default to ensure you can get a full picture of your microservices out of the box.

    Istio has migrated away from Helm as a way to install Istio and now provides installation through the istioctl binary or Istio Operator. To ensure the easiest interaction with Istio, Rancher's Istio will maintain a Helm chart that utilizes the istioctl binary to manage your Istio installation.

    This Helm chart will be available via the Apps and Marketplace in the UI. A user that has access to the Rancher Chart's catalog will need to set up Istio before it can be used in the project.

    Tools Bundled with Istio​

    Our Istio installer wraps the istioctl binary commands in a handy Helm chart, including an overlay file option to allow complex customization.

    It also includes the following:

    Kiali​

    Kiali is a comprehensive visualization aid used for graphing traffic flow throughout the service mesh. It allows you to see how they are connected, including the traffic rates and latencies between them.

    You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.

    Jaeger​

    Our Istio installer includes a quick-start, all-in-one installation of Jaeger, a tool used for tracing distributed systems.

    Note that this is not a production-qualified deployment of Jaeger. This deployment uses an in-memory storage component, while a persistent storage component is recommended for production. For more information on which deployment strategy you may need, refer to the Jaeger documentation.

    Prerequisites​

    Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

    If you are installing Istio on RKE2 cluster, some additional steps are required. For details, see this section.

    Note that Istio v2 (upstream Istio v1.7+) cannot be upgraded in an air gapped environment.

    Setup Guide​

    Refer to the setup guide for instructions on how to set up Istio and use it in a project.

    Remove Istio​

    To remove Istio components from a cluster, namespace, or workload, refer to the section on uninstalling Istio.

    Migrate From Previous Istio Version​

    There is no upgrade path for Istio versions less than 1.7.x. To successfully install Istio through Apps & Marketplace, you will need to disable your existing Istio from the global view in the legacy Rancher UI.

    If you have a significant amount of additional Istio CRDs you might consider manually migrating CRDs that are supported in both versions of Istio. You can do this by running kubectl get <resource> -n istio-system -o yaml, save the output yaml and re-apply in the new version.

    Another option is to manually uninstall istio resources one at a time, but leave the resources that are supported in both versions of Istio and that will not be installed by the newest version. This method is more likely to result in issues installing the new version, but could be a good option depending on your situation.

    Accessing Visualizations​

    By default, only cluster-admins have access to Kiali. For instructions on how to allow admin, edit or views roles to access them, see this section.

    After Istio is set up in a cluster, Grafana, Prometheus, and Kiali are available in the Rancher UI.

    To access the Grafana and Prometheus visualizations,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to see the visualizations and click Explore.
    3. In the left navigation bar, click Monitoring.
    4. Click Grafana or any of the other dashboards.

    To access the Kiali visualization,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to see Kiali and click Explore.
    3. In the left navigation bar, click Istio.
    4. Click Kiali. From here you can access the Traffic Graph tab or the Traffic Metrics tab to see network visualizations and metrics.

    By default, all namespace will picked up by prometheus and make data available for Kiali graphs. Refer to selector/scrape config setup if you would like to use a different configuration for prometheus data scraping.

    Your access to the visualizations depend on your role. Grafana and Prometheus are only available for cluster-admin roles. The Kiali UI is available only to cluster-admin by default, but cluster-admin can allow other roles to access them by editing the Istio values.yaml.

    Architecture​

    Istio installs a service mesh that uses Envoy sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.

    Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.

    When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.

    For more information on the Istio sidecar, refer to the Istio sidecare-injection docs and for more information on Istio's architecture, refer to the Istio Architecture docs

    Multiple Ingresses​

    By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. Istio also installs an ingress gateway by default into the istio-system namespace. The result is that your cluster will have two ingresses in your cluster.

    In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.

    Additional Istio Ingress gateways can be enabled via the overlay file.

    Egress Support​

    By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the overlay file.

    Additional Steps for Installing Istio on an RKE2 Cluster​

    To install Istio on an RKE2 cluster, follow the steps in this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/kubernetes-cluster-setup.html b/pages-for-subheaders/kubernetes-cluster-setup.html index 6eef6ba5eca..345459046d8 100644 --- a/pages-for-subheaders/kubernetes-cluster-setup.html +++ b/pages-for-subheaders/kubernetes-cluster-setup.html @@ -5,13 +5,13 @@ Don't have a Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
    Version: v2.6

    Don't have a Kubernetes cluster? Try one of these tutorials.

    This section contains information on how to install a Kubernetes cluster that the Rancher server can be installed on.

    Rancher can run on any Kubernetes cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html b/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html index 45cc9c4a159..d1179174a8a 100644 --- a/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html +++ b/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html @@ -5,13 +5,13 @@ Setting up Kubernetes Clusters in Rancher | Rancher Manager - +
    Version: v2.6

    Setting up Kubernetes Clusters in Rancher

    Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the architecture page.

    Cluster Management Capabilities by Cluster Type​

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher Launched Kubernetes ClustersEKS, GKE and AKS Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Monitoring, Logging, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Setting up Clusters in a Hosted Kubernetes Provider​

    In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

    For more information, refer to the section on hosted Kubernetes clusters.

    Launching Kubernetes with Rancher​

    Rancher uses the Rancher Kubernetes Engine (RKE) as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer.

    In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform.

    These nodes can be dynamically provisioned through Rancher's UI, which calls Docker Machine to launch nodes on various cloud providers.

    If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it.

    For more information, refer to the section on RKE clusters.

    Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider​

    Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

    Using Rancher, you can create pools of nodes based on a node template. This template defines the parameters used to launch nodes in your cloud providers.

    One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration.

    The cloud providers available for creating a node template are decided based on the node drivers active in the Rancher UI.

    For more information, refer to the section on nodes hosted by an infrastructure provider

    Launching Kubernetes on Existing Custom Nodes​

    When setting up this type of cluster, Rancher installs Kubernetes on existing custom nodes, which creates a custom cluster.

    You can bring any nodes you want to Rancher and use them to create a cluster.

    These nodes include on-prem bare metal servers, cloud-hosted virtual machines, or on-prem virtual machines.

    Registering Existing Clusters​

    The cluster registration feature replaces the feature to import clusters.

    Registering EKS clusters now provides additional benefits. For the most part, registered EKS clusters and EKS clusters created in Rancher are treated the same way in the Rancher UI, except for deletion.

    When you delete an EKS cluster that was created in Rancher, the cluster is destroyed. When you delete an EKS cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.

    For more information, see this page.

    Programmatically Creating Clusters​

    The most common way to programmatically deploy Kubernetes clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    EKS, GKE, AKS clusters and RKE clusters can be created or imported with Terraform.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/kubernetes-components.html b/pages-for-subheaders/kubernetes-components.html index 895a5290bd7..bacea667da9 100644 --- a/pages-for-subheaders/kubernetes-components.html +++ b/pages-for-subheaders/kubernetes-components.html @@ -5,13 +5,13 @@ Kubernetes Components | Rancher Manager - +
    Version: v2.6

    Kubernetes Components

    The commands and steps listed in this section apply to the core Kubernetes components on Rancher Launched Kubernetes clusters.

    This section includes troubleshooting tips in the following categories:

    Kubernetes Component Diagram

    Cluster diagram

    Lines show the traffic flow between components. Colors are used purely for visual aid
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/kubernetes-resources-setup.html b/pages-for-subheaders/kubernetes-resources-setup.html index bc87bb2cd56..91044816199 100644 --- a/pages-for-subheaders/kubernetes-resources-setup.html +++ b/pages-for-subheaders/kubernetes-resources-setup.html @@ -5,13 +5,13 @@ Kubernetes Resources | Rancher Manager - +
    Version: v2.6

    Kubernetes Resources

    You can view and manipulate all of the custom resources and CRDs in a Kubernetes cluster from the Rancher UI.

    Workloads​

    Deploy applications to your cluster nodes using workloads, which are objects that contain pods that run your apps, along with metadata that set rules for the deployment's behavior. Workloads can be deployed within the scope of the entire clusters or within a namespace.

    When deploying a workload, you can deploy from any image. There are a variety of workload types to choose from which determine how your application should run.

    Following a workload deployment, you can continue working with it. You can:

    • Upgrade the workload to a newer version of the application it's running.
    • Roll back a workload to a previous version, if an issue occurs during upgrade.
    • Add a sidecar, which is a workload that supports a primary workload.

    Load Balancing and Ingress​

    Load Balancers​

    After you launch an application, it's only available within the cluster. It can't be reached externally.

    If you want your applications to be externally accessible, you must add a load balancer to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

    Rancher supports two types of load balancers:

    For more information, see load balancers.

    Ingress​

    Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive. You can get around this issue by using an ingress.

    Ingress is a set of rules that act as a load balancer. Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster program the load balancer to direct the request to the correct service based on service subdomains or path rules that you've configured.

    For more information, see Ingress.

    When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    Service Discovery​

    After you expose your cluster to external requests using a load balancer and/or ingress, it's only available by IP address. To create a resolveable hostname, you must create a service record, which is a record that maps an IP address, external hostname, DNS record alias, workload(s), or labelled pods to a specific hostname.

    For more information, see Service Discovery.

    Pipelines​

    After your project has been configured to a version control provider, you can add the repositories and start configuring a pipeline for each repository.

    For more information, see Pipelines.

    Applications​

    Besides launching individual components of an application, you can use the Rancher catalog to start launching applications, which are Helm charts.

    Kubernetes Resources​

    Within the context of a Rancher project or namespace, resources are files and data that support operation of your pods. Within Rancher, certificates, registries, and secrets are all considered resources. However, Kubernetes classifies resources as different types of secrets. Therefore, within a single project or namespace, individual resources must have unique names to avoid conflicts. Although resources are primarily used to carry sensitive information, they have other uses as well.

    Resources include:

    • Certificates: Files used to encrypt/decrypt data entering or leaving the cluster.
    • ConfigMaps: Files that store general configuration information, such as a group of config files.
    • Secrets: Files that store sensitive data like passwords, tokens, or keys.
    • Registries: Files that carry credentials used to authenticate with private registries.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/launch-kubernetes-with-rancher.html b/pages-for-subheaders/launch-kubernetes-with-rancher.html index a5bcc7b517a..ec677e8a64f 100644 --- a/pages-for-subheaders/launch-kubernetes-with-rancher.html +++ b/pages-for-subheaders/launch-kubernetes-with-rancher.html @@ -5,13 +5,13 @@ Launching Kubernetes with Rancher | Rancher Manager - +
    Version: v2.6

    Launching Kubernetes with Rancher

    You can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, you can choose between Rancher Kubernetes Engine (RKE) or RKE2 distributions. Rancher can launch Kubernetes on any computers, including:

    • Bare-metal servers
    • On-premise virtual machines
    • Virtual machines hosted by an infrastructure provider

    Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them.

    Rancher can also create pools of nodes. One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

    RKE​

    Requirements​

    If you use RKE to set up a cluster, your nodes must meet the requirements for nodes in downstream user clusters.

    Launching Kubernetes on New Nodes in an Infrastructure Provider​

    Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your cloud providers.

    One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

    For more information, refer to the section on launching Kubernetes on new nodes.

    Launching Kubernetes on Existing Custom Nodes​

    In this scenario, you want to install Kubernetes on bare-metal servers, on-prem virtual machines, or virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine.

    If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

    For more information, refer to the section on custom nodes.

    Programmatically Creating RKE Clusters

    The most common way to programmatically deploy RKE clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    RKE2​

    Rancher v2.6 introduced provisioning for RKE2 clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector. In Rancher v.2.6.4 and earlier, RKE2 provisioning was in tech preview.

    Note that in Rancher v2.6.5, RKE2 provisioning became GA.

    Requirements​

    If you use RKE2 to set up a cluster, your nodes must meet the requirements for nodes in downstream user clusters.

    Launching Kubernetes on New Nodes in an Infrastructure Provider​

    RKE2 provisioning is built on top of a new provisioning framework that leverages the upstream Cluster API project. With this new provisioning framework, you can:

    • Provision RKE2 clusters onto any provider for which Rancher has a node driver
    • Fully configure RKE2 clusters within Rancher
    • Choose CNI options Calico, Cilium, and Multus in addition to Canal

    RKE2 provisioning also includes installing RKE2 on clusters with Windows nodes.

    Windows features for RKE2 include:

    • Windows supports the vSphere node driver
    • Calico CNI for Windows RKE2 custom clusters
    • Project Network Isolation (PNI) for Calico
    • Windows Containers with RKE2 powered by containerd
    • Provisioning of Windows RKE2 clusters through Terraform
    • Provisioning of Windows RKE2 custom clusters directly from the Rancher UI

    Windows Support for RKE2 Custom Clusters requires choosing Calico as the CNI.

    Launching Kubernetes on Existing Custom Nodes​

    RKE2 provisioning also allows you to install custom clusters on pre-provisioned VMs or bare-metal nodes.

    If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

    Programmatically Creating RKE2 Clusters

    The most common way to programmatically deploy RKE2 clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/load-balancer-and-ingress-controller.html b/pages-for-subheaders/load-balancer-and-ingress-controller.html index c706ada66ef..08abd73ffed 100644 --- a/pages-for-subheaders/load-balancer-and-ingress-controller.html +++ b/pages-for-subheaders/load-balancer-and-ingress-controller.html @@ -5,13 +5,13 @@ Set Up Load Balancer and Ingress Controller within Rancher | Rancher Manager - +
    Version: v2.6

    Set Up Load Balancer and Ingress Controller within Rancher

    Within Rancher, you can set up load balancers and ingress controllers to redirect service requests.

    Load Balancers​

    After you launch an application, the app is only available within the cluster. It can't be reached from outside the cluster.

    If you want your applications to be externally accessible, you must add a load balancer or ingress to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

    Rancher supports two types of load balancers:

    For more information, see load balancers.

    Load Balancer Limitations​

    Load Balancers have a couple of limitations you should be aware of:

    • Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive.

    • If you want to use a load balancer with a Hosted Kubernetes cluster (i.e., clusters hosted in GKE, EKS, or AKS), the load balancer must be running within that cloud provider's infrastructure. Please review the compatibility tables regarding support for load balancers based on how you've provisioned your clusters:

    • Support for Layer-4 Load Balancing

    • Support for Layer-7 Load Balancing

    Ingress​

    As mentioned in the limitations above, the disadvantages of using a load balancer are:

    • Load Balancers can only handle one IP address per service.
    • If you run multiple services in your cluster, you must have a load balancer for each service.
    • It can be expensive to have a load balancer for every service.

    In contrast, when an ingress is used as the entrypoint into a cluster, the ingress can route traffic to multiple services with greater flexibility. It can map multiple HTTP requests to services without individual IP addresses for each service.

    Therefore, it is useful to have an ingress if you want multiple services to be exposed with the same IP address, the same Layer 7 protocol, or the same privileged node-ports: 80 and 443.

    Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster direct the request to the correct service based on service subdomains or path rules that you've configured.

    Each Kubernetes Ingress resource corresponds roughly to a file in /etc/nginx/sites-available/ containing a server{} configuration block, where requests for specific files and folders are configured.

    Your ingress, which creates a port of entry to your cluster similar to a load balancer, can reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launched clusters are powered by Nginx.

    Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more.

    Using Rancher in a High Availability Configuration?

    Refrain from adding an Ingress to the local cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for all clusters managed by Rancher, including the local cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher.

    • For more information on how to set up ingress in Rancher, see Ingress.
    • For complete information about ingress and ingress controllers, see the Kubernetes Ingress Documentation
    • When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/logging.html b/pages-for-subheaders/logging.html index 3c5b8e359fe..188d0dcfbce 100644 --- a/pages-for-subheaders/logging.html +++ b/pages-for-subheaders/logging.html @@ -5,7 +5,7 @@ Rancher Integration with Logging Services | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.6

    Rancher Integration with Logging Services

    The Banzai Cloud Logging operator now powers Rancher's logging solution in place of the former, in-house solution.

    For an overview of the changes in v2.5, see this section. For information about migrating from Logging V1, see this page.

    Enabling Logging​

    You can enable the logging for a Rancher managed cluster by going to the Apps page and installing the logging app.

    1. Go to the cluster where you want to install logging and click Apps & Marketplace.
    2. Click the Logging app.
    3. Scroll to the bottom of the Helm chart README and click Install.

    Result: The logging app is deployed in the cattle-logging-system namespace.

    Uninstall Logging​

    1. Go to the cluster where you want to install logging and click Apps & Marketplace.
    2. Click Installed Apps.
    3. Go to the cattle-logging-system namespace and check the boxes for rancher-logging and rancher-logging-crd.
    4. Click Delete.
    5. Confirm Delete.

    Result rancher-logging is uninstalled.

    Architecture​

    For more information about how the logging application works, see this section.

    Role-based Access Control​

    Rancher logging has two roles, logging-admin and logging-view. For more information on how and when to use these roles, see this page.

    Configuring Logging Custom Resources​

    To manage Flows, ClusterFlows, Outputs, and ClusterOutputs,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to configure logging custom resources and click Explore.
    3. In the left navigation bar, click Logging.

    Flows and ClusterFlows​

    For help with configuring Flows and ClusterFlows, see this page.

    Outputs and ClusterOutputs​

    For help with configuring Outputs and ClusterOutputs, see this page.

    Configuring the Logging Helm Chart​

    For a list of options that can be configured when the logging application is installed or upgraded, see this page.

    Windows Support​

    Logging support for Windows clusters is available and logs can be collected from Windows nodes.

    For details on how to enable or disable Windows node logging, see this section.

    Working with a Custom Docker Root Directory​

    For details on using a custom Docker root directory, see this section.

    Working with Taints and Tolerations​

    For information on how to use taints and tolerations with the logging application, see this page.

    Logging V2 with SELinux​

    For information on enabling the logging application for SELinux-enabled nodes, see this section.

    Additional Logging Sources​

    By default, Rancher collects logs for control plane components and node components for all cluster types. In some cases additional logs can be collected. For details, see this section.

    Troubleshooting​

    The cattle-logging Namespace Being Recreated​

    If your cluster previously deployed logging from the global view in the legacy Rancher UI, you may encounter an issue where its cattle-logging namespace is continually being recreated.

    The solution is to delete all clusterloggings.management.cattle.io and projectloggings.management.cattle.io custom resources from the cluster specific namespace in the management cluster. The existence of these custom resources causes Rancher to create the cattle-logging namespace in the downstream cluster if it does not exist.

    The cluster namespace matches the cluster ID, so we need to find the cluster ID for each cluster.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster you want to get the ID of and click Explore.
    3. Copy the <cluster-id> portion from one of the URLs below. The <cluster-id> portion is the cluster namespace name.
    # Cluster Management UI
    https://<your-url>/c/<cluster-id>/

    # Cluster Dashboard
    https://<your-url>/dashboard/c/<cluster-id>/

    Now that we have the <cluster-id> namespace, we can delete the CRs that cause cattle-logging to be continually recreated. Warning: ensure that logging, the version installed from the global view in the legacy Rancher UI, is not currently in use.

    kubectl delete clusterloggings.management.cattle.io -n <cluster-id>
    kubectl delete projectloggings.management.cattle.io -n <cluster-id>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/machine-configuration.html b/pages-for-subheaders/machine-configuration.html index 540de13faa5..1e46c9db984 100644 --- a/pages-for-subheaders/machine-configuration.html +++ b/pages-for-subheaders/machine-configuration.html @@ -5,13 +5,13 @@ Machine Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/manage-clusters.html b/pages-for-subheaders/manage-clusters.html index 26d229c9c97..7fc9792a314 100644 --- a/pages-for-subheaders/manage-clusters.html +++ b/pages-for-subheaders/manage-clusters.html @@ -5,13 +5,13 @@ Cluster Administration | Rancher Manager - +
    Version: v2.6

    Cluster Administration

    After you provision a cluster in Rancher, you can begin using powerful Kubernetes features to deploy and scale your containerized applications in development, testing, or production environments.

    This page covers the following topics:

    note

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    Managing Clusters in Rancher​

    After clusters have been provisioned into Rancher, cluster owners will need to manage these clusters. There are many different options of how to manage your cluster.

    ActionRancher Launched Kubernetes ClustersEKS, GKE and AKS Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Monitoring, Logging, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Configuring Tools​

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into the following categories:

    • Alerts
    • Notifiers
    • Logging
    • Monitoring
    • Istio Service Mesh
    • OPA Gatekeeper

    Tools can be installed through Apps & Marketplace.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/manage-persistent-storage.html b/pages-for-subheaders/manage-persistent-storage.html index fa7683ef2fb..27ecf208e9d 100644 --- a/pages-for-subheaders/manage-persistent-storage.html +++ b/pages-for-subheaders/manage-persistent-storage.html @@ -5,13 +5,13 @@ Manage Persistent Storage | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/manage-project-resource-quotas.html b/pages-for-subheaders/manage-project-resource-quotas.html index bfce015fc86..c74c99a7fba 100644 --- a/pages-for-subheaders/manage-project-resource-quotas.html +++ b/pages-for-subheaders/manage-project-resource-quotas.html @@ -5,13 +5,13 @@ Project Resource Quotas | Rancher Manager - +
    Version: v2.6

    Project Resource Quotas

    In situations where several teams share a cluster, one team may overconsume the resources available: CPU, memory, storage, services, Kubernetes objects like pods or secrets, and so on. To prevent this overconsumption, you can apply a resource quota, which is a Rancher feature that limits the resources available to a project or namespace.

    This page is a how-to guide for creating resource quotas in existing projects.

    Resource quotas can also be set when a new project is created. For details, refer to the section on creating new projects.

    Resource quotas in Rancher include the same functionality as the native version of Kubernetes. In Rancher, resource quotas have been extended so that you can apply them to projects. For details on how resource quotas work with projects in Rancher, refer to this page.

    Applying Resource Quotas to Existing Projects​

    Edit resource quotas when:

    • You want to limit the resources that a project and its namespaces can use.
    • You want to scale the resources available to a project up or down when a research quota is already in effect.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to apply a resource quota and click Explore.

    3. Click Cluster > Projects/Namespaces.

    4. Find the project that you want to add a resource quota to. From that project, select ⋮ > Edit Config.

    5. Expand Resource Quotas and click Add Resource. Alternatively, you can edit existing quotas.

    6. Select a Resource Type. For more information on types, see the quota type reference.

    7. Enter values for the Project Limit and the Namespace Default Limit.

      FieldDescription
      Project LimitThe overall resource limit for the project.
      Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit.

    8. Optional: Add more quotas.

    9. Click Create.

    Result: The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/manage-projects.html b/pages-for-subheaders/manage-projects.html index 9c06b502216..5d4cd7c977d 100644 --- a/pages-for-subheaders/manage-projects.html +++ b/pages-for-subheaders/manage-projects.html @@ -5,13 +5,13 @@ Project Administration | Rancher Manager - +
    Version: v2.6

    Project Administration

    Projects are objects introduced in Rancher that help organize namespaces in your Kubernetes cluster. You can use projects to create multi-tenant clusters, which allows a group of users to share the same underlying resources without interacting with each other's applications.

    In terms of hierarchy:

    • Clusters contain projects
    • Projects contain namespaces

    Within Rancher, projects allow you to manage multiple namespaces as a single entity. In native Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace!

    Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each individual namespace.

    You can use projects to perform actions like:

    Authorization​

    Non-administrative users are only authorized for project access after an administrator, cluster owner or member, or project owner adds them to the project's Members tab.

    Whoever creates the project automatically becomes a project owner.

    Switching between Projects​

    To switch between projects, use the drop-down available in the navigation bar. Alternatively, you can switch between projects directly in the navigation bar.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to switch projects and click Explore.
    3. In the top navigation bar, select the project that you want to open.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/manage-role-based-access-control-rbac.html b/pages-for-subheaders/manage-role-based-access-control-rbac.html index f1a462fe34b..359079aaad4 100644 --- a/pages-for-subheaders/manage-role-based-access-control-rbac.html +++ b/pages-for-subheaders/manage-role-based-access-control-rbac.html @@ -5,13 +5,13 @@ Role-Based Access Control (RBAC) | Rancher Manager - +
    Version: v2.6

    Role-Based Access Control (RBAC)

    Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. As mentioned in Authentication, users can either be local or external.

    After you configure external authentication, the users that display on the Users page changes.

    • If you are logged in as a local user, only local users display.

    • If you are logged in as an external user, both external and local users display.

    Users and Roles​

    Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by global permissions, and cluster and project roles.

    • Global Permissions:

      Define user authorization outside the scope of any particular cluster.

    • Cluster and Project Roles:

      Define user authorization inside the specific cluster or project where they are assigned the role.

    Both global permissions and cluster and project roles are implemented on top of Kubernetes RBAC. Therefore, enforcement of permissions and roles is performed by Kubernetes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/monitoring-alerting-guides.html b/pages-for-subheaders/monitoring-alerting-guides.html index 95b0b24e65d..75c7daf6971 100644 --- a/pages-for-subheaders/monitoring-alerting-guides.html +++ b/pages-for-subheaders/monitoring-alerting-guides.html @@ -5,13 +5,13 @@ Monitoring Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/monitoring-and-alerting.html b/pages-for-subheaders/monitoring-and-alerting.html index 311ac4490e1..4cd32996895 100644 --- a/pages-for-subheaders/monitoring-and-alerting.html +++ b/pages-for-subheaders/monitoring-and-alerting.html @@ -5,13 +5,13 @@ Monitoring and Alerting | Rancher Manager - +
    Version: v2.6

    Monitoring and Alerting

    Using the rancher-monitoring application, you can quickly deploy leading open-source monitoring and alerting solutions onto your cluster.

    Features​

    Prometheus lets you view metrics from your Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus.

    By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, or restore crashed servers.

    The rancher-monitoring operator, introduced in Rancher v2.5, is powered by Prometheus, Grafana, Alertmanager, the Prometheus Operator, and the Prometheus adapter.

    The monitoring application allows you to:

    • Monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments
    • Define alerts based on metrics collected via Prometheus
    • Create custom Grafana dashboards
    • Configure alert-based notifications via Email, Slack, PagerDuty, etc. using Prometheus Alertmanager
    • Defines precomputed, frequently needed or computationally expensive expressions as new time series based on metrics collected via Prometheus
    • Expose collected metrics from Prometheus to the Kubernetes Custom Metrics API via Prometheus Adapter for use in HPA

    How Monitoring Works

    For an explanation of how the monitoring components work together, see this page.

    Default Components and Deployments

    Built-in Dashboards​

    By default, the monitoring application deploys Grafana dashboards (curated by the kube-prometheus project) onto a cluster.

    It also deploys an Alertmanager UI and a Prometheus UI. For more information about these tools, see Built-in Dashboards.

    Default Metrics Exporters​

    By default, Rancher Monitoring deploys exporters (such as node-exporter and kube-state-metrics).

    These default exporters automatically scrape metrics for CPU and memory from all components of your Kubernetes cluster, including your workloads.

    Default Alerts​

    The monitoring application deploys some alerts by default. To see the default alerts, go to the Alertmanager UI and click Expand all groups.

    Components Exposed in the Rancher UI​

    For a list of monitoring components exposed in the Rancher UI, along with common use cases for editing them, see this section.

    Role-based Access Control

    For information on configuring access to monitoring, see this page.

    Guides

    Configuration

    Configuring Monitoring Resources in Rancher​

    The configuration reference assumes familiarity with how monitoring components work together. For more information, see How Monitoring Works.

    Configuring Helm Chart Options​

    For more information on rancher-monitoring chart options, including options to set resource limits and requests, see this page.

    Windows Cluster Support

    When deployed onto an RKE1 Windows cluster, Monitoring V2 will now automatically deploy a windows-exporter DaemonSet and set up a ServiceMonitor to collect metrics from each of the deployed Pods. This will populate Prometheus with windows_ metrics that are akin to the node_ metrics exported by node_exporter for Linux hosts.

    To be able to fully deploy Monitoring V2 for Windows, all of your Windows hosts must have a minimum wins version of v0.1.0.

    For more details on how to upgrade wins on existing Windows hosts, refer to the section on Windows cluster support for Monitoring V2.

    Known Issues

    There is a known issue that K3s clusters require more default memory. If you are enabling monitoring on a K3s cluster, we recommend to setting prometheus.prometheusSpec.resources.memory.limit to 2500 Mi and prometheus.prometheusSpec.resources.memory.request to 1750 Mi.

    For tips on debugging high memory usage, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/monitoring-v2-configuration-guides.html b/pages-for-subheaders/monitoring-v2-configuration-guides.html index f058c2bbe29..752feadc027 100644 --- a/pages-for-subheaders/monitoring-v2-configuration-guides.html +++ b/pages-for-subheaders/monitoring-v2-configuration-guides.html @@ -5,13 +5,13 @@ Configuration | Rancher Manager - +
    Version: v2.6

    Configuration

    This page captures some of the most important options for configuring Monitoring V2 in the Rancher UI.

    For information on configuring custom scrape targets and rules for Prometheus, please refer to the upstream documentation for the Prometheus Operator. Some of the most important custom resources are explained in the Prometheus Operator design documentation. The Prometheus Operator documentation can help also you set up RBAC, Thanos, or custom configuration.

    Setting Resource Limits and Requests

    The resource requests and limits for the monitoring application can be configured when installing rancher-monitoring. For more information about the default limits, see this page.

    note

    On an idle cluster, Monitoring V2 has significantly higher CPU usage (up to 70%) as compared to Monitoring V1. To improve performance and achieve similar results as in Monitoring V1, turn off the Prometheus adapter.

    Prometheus Configuration

    It is usually not necessary to directly edit the Prometheus custom resource.

    Instead, to configure Prometheus to scrape custom metrics, you will only need to create a new ServiceMonitor or PodMonitor to configure Prometheus to scrape additional metrics.

    ServiceMonitor and PodMonitor Configuration​

    For details, see this page.

    Advanced Prometheus Configuration​

    For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see this page.

    Alertmanager Configuration

    The Alertmanager custom resource usually doesn't need to be edited directly. For most common use cases, you can manage alerts by updating Routes and Receivers.

    Routes and receivers are part of the configuration of the alertmanager custom resource. In the Rancher UI, Routes and Receivers are not true custom resources, but pseudo-custom resources that the Prometheus Operator uses to synchronize your configuration with the Alertmanager custom resource. When routes and receivers are updated, the monitoring application will automatically update Alertmanager to reflect those changes.

    For some advanced use cases, you may want to configure alertmanager directly. For more information, refer to this page.

    Receivers​

    Receivers are used to set up notifications. For details on how to configure receivers, see this page.

    Routes​

    Routes filter notifications before they reach receivers. Each route needs to refer to a receiver that has already been configured. For details on how to configure routes, see this page.

    Advanced​

    For more information about directly editing the Alertmanager custom resource, which may be helpful in advanced use cases, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/monitoring-v2-configuration.html b/pages-for-subheaders/monitoring-v2-configuration.html index a2cb4f29b62..42ac3bb05b6 100644 --- a/pages-for-subheaders/monitoring-v2-configuration.html +++ b/pages-for-subheaders/monitoring-v2-configuration.html @@ -5,13 +5,13 @@ Monitoring V2 Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/new-user-guides.html b/pages-for-subheaders/new-user-guides.html index 7b4cc435b0a..ddd51bfcb27 100644 --- a/pages-for-subheaders/new-user-guides.html +++ b/pages-for-subheaders/new-user-guides.html @@ -5,13 +5,13 @@ New User Guides | Rancher Manager - +
    Version: v2.6

    New User Guides

    New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

    The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

    The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/node-template-configuration.html b/pages-for-subheaders/node-template-configuration.html index 0ff258f425b..ac37f4d1947 100644 --- a/pages-for-subheaders/node-template-configuration.html +++ b/pages-for-subheaders/node-template-configuration.html @@ -5,13 +5,13 @@ Node Template Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/nutanix.html b/pages-for-subheaders/nutanix.html index 59a39a3ff86..5608f36da16 100644 --- a/pages-for-subheaders/nutanix.html +++ b/pages-for-subheaders/nutanix.html @@ -5,13 +5,13 @@ Creating a Nutanix AOS Cluster | Rancher Manager - +
    Version: v2.6

    Creating a Nutanix AOS Cluster

    Nutanix Acropolis Operating System (Nutanix AOS) is an operating system for the Nutanix hyper-converged infrastructure platform. AOS comes with a built-in hypervisor called Acropolis Hypervisor, or AHV. By using Rancher with Nutanix AOS (AHV), you can bring cloud operations on-premises.

    Rancher can provision nodes in AOS (AHV) and install Kubernetes on them. When creating a Kubernetes cluster in AOS, Rancher first provisions the specified number of virtual machines by communicating with the Prism Central API. Then it installs Kubernetes on top of the VMs.

    A Nutanix cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role.

    Creating a Nutanix Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in Nutanix AOS.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/other-cloud-providers.html b/pages-for-subheaders/other-cloud-providers.html index c2acf97e887..7dddb194ff8 100644 --- a/pages-for-subheaders/other-cloud-providers.html +++ b/pages-for-subheaders/other-cloud-providers.html @@ -5,13 +5,13 @@ Other Cloud Providers | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/other-installation-methods.html b/pages-for-subheaders/other-installation-methods.html index b571f47928e..ed1281c06ed 100644 --- a/pages-for-subheaders/other-installation-methods.html +++ b/pages-for-subheaders/other-installation-methods.html @@ -5,13 +5,13 @@ Other Installation Methods | Rancher Manager - +
    Version: v2.6

    Other Installation Methods

    Air Gapped Installations​

    Follow these steps to install the Rancher server in an air gapped environment.

    An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Docker Installations​

    The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

    The Docker installation is for development and testing environments only.

    Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/other-troubleshooting-tips.html b/pages-for-subheaders/other-troubleshooting-tips.html index 999d383ef4d..9a430de8fdc 100644 --- a/pages-for-subheaders/other-troubleshooting-tips.html +++ b/pages-for-subheaders/other-troubleshooting-tips.html @@ -5,13 +5,13 @@ Other Troubleshooting Tips | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/pipelines.html b/pages-for-subheaders/pipelines.html index 3ef6b037d30..8b6cdc47dd2 100644 --- a/pages-for-subheaders/pipelines.html +++ b/pages-for-subheaders/pipelines.html @@ -5,13 +5,13 @@ Pipelines | Rancher Manager - +
    Version: v2.6

    Pipelines

    Notes

    • As of Rancher v2.5, Git-based deployment pipelines are now deprecated. We recommend handling pipelines with Rancher Continuous Delivery powered by Fleet. To get to Fleet in Rancher, click ☰ > Continuous Delivery.

    • Pipelines in Kubernetes 1.21+ are no longer supported.

    • Fleet does not replace Rancher pipelines; the distinction is that Rancher pipelines are now powered by Fleet.

    Rancher's pipeline provides a simple CI/CD experience. Use it to automatically checkout code, run builds or scripts, publish Docker images or catalog applications, and deploy the updated software to users.

    Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

    After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

    • Build your application from code to image.
    • Validate your builds.
    • Deploy your build images to your cluster.
    • Run unit tests.
    • Run regression tests.
    note

    Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses.

    Concepts​

    For an explanation of concepts and terminology used in this section, refer to this page.

    How Pipelines Work​

    After enabling the ability to use pipelines in a project, you can configure multiple pipelines in each project. Each pipeline is unique and can be configured independently.

    A pipeline is configured off of a group of files that are checked into source code repositories. Users can configure their pipelines either through the Rancher UI or by adding a .rancher-pipeline.yml into the repository.

    Before pipelines can be configured, you will need to configure authentication to your version control provider, e.g. GitHub, GitLab, Bitbucket. If you haven't configured a version control provider, you can always use Rancher's example repositories to view some common pipeline deployments.

    When you configure a pipeline in one of your projects, a namespace specifically for the pipeline is automatically created. The following components are deployed to it:

    • Jenkins:

      The pipeline's build engine. Because project users do not directly interact with Jenkins, it's managed and locked.

      note

      There is no option to use existing Jenkins deployments as the pipeline engine.

    • Docker Registry:

      Out-of-the-box, the default target for your build-publish step is an internal Docker Registry. However, you can make configurations to push to a remote registry instead. The internal Docker Registry is only accessible from cluster nodes and cannot be directly accessed by users. Images are not persisted beyond the lifetime of the pipeline and should only be used in pipeline runs. If you need to access your images outside of pipeline runs, please push to an external registry.

    • Minio:

      Minio storage is used to store the logs for pipeline executions.

      note

      The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in data persistency for pipeline components.

    Role-based Access Control for Pipelines​

    If you can access a project, you can enable repositories to start building pipelines.

    Only administrators, cluster owners or members, or project owners can configure version control providers and manage global pipeline execution settings.

    Project members can only configure repositories and pipelines.

    Setting up Pipelines​

    Prerequisite​

    Legacy Feature Flag:

    Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported.

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags.
    3. Go to the legacy feature flag and click ⋮ > Activate.
    1. Configure version control providers
    2. Configure repositories
    3. Configure the pipeline

    1. Configure Version Control Providers​

    Before you can start configuring a pipeline for your repository, you must configure and authorize a version control provider:

    • GitHub
    • GitLab
    • Bitbucket

    Select your provider's tab below and follow the directions.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.
    5. Click the Configuration tab.
    6. Follow the directions displayed to Setup a Github application. Rancher redirects you to Github to set up an OAuth App in Github.
    7. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.
    8. If you're using GitHub for enterprise, select Use a private github enterprise installation. Enter the host address of your GitHub installation.
    9. Click Authenticate.

    Result: After the version control provider is authenticated, you will be automatically re-directed to start configuring which repositories you want start using with a pipeline.

    2. Configure Repositories​

    After the version control provider is authorized, you are automatically re-directed to start configuring which repositories that you want start using pipelines with. Even if someone else has set up the version control provider, you will see their repositories and can build a pipeline.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. Click on Configure Repositories.

    6. A list of repositories are displayed. If you are configuring repositories the first time, click on Authorize & Fetch Your Own Repositories to fetch your repository list.

    7. For each repository that you want to set up a pipeline, click on Enable.

    8. When you're done enabling all your repositories, click on Done.

    Results: You have a list of repositories that you can start configuring pipelines for.

    3. Configure the Pipeline​

    Now that repositories are added to your project, you can start configuring the pipeline by adding automated stages and steps. For your convenience, there are multiple built-in step types for dedicated tasks.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. Find the repository that you want to set up a pipeline for.

    6. Configure the pipeline through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml. Pipeline configuration is split into stages and steps. Stages must fully complete before moving onto the next stage, but steps in a stage run concurrently. For each stage, you can add different step types. Note: As you build out each step, there are different advanced options based on the step type. Advanced options include trigger rules, environment variables, and secrets. For more information on configuring the pipeline through the UI or the YAML file, refer to the pipeline configuration reference.

      • If you are going to use the UI, select the vertical ⋮ > Edit Config to configure the pipeline using the UI. After the pipeline is configured, you must view the YAML file and push it to the repository.
      • If you are going to use the YAML file, select the vertical ⋮ > View/Edit YAML to configure the pipeline. If you choose to use a YAML file, you need to push it to the repository after any changes in order for it to be updated in the repository. When editing the pipeline configuration, it takes a few moments for Rancher to check for an existing pipeline configuration.

    7. Select which branch to use from the list of branches.

    8. Optional: Set up notifications.

    9. Set up the trigger rules for the pipeline.

    10. Enter a Timeout for the pipeline.

    11. When all the stages and steps are configured, click Done.

    Results: Your pipeline is now configured and ready to be run.

    Pipeline Configuration Reference​

    Refer to this page for details on how to configure a pipeline to:

    • Run a script
    • Build and publish images
    • Publish catalog templates
    • Deploy YAML
    • Deploy a catalog app

    The configuration reference also covers how to configure:

    • Notifications
    • Timeouts
    • The rules that trigger a pipeline
    • Environment variables
    • Secrets

    Running your Pipelines​

    Run your pipeline for the first time. Find your pipeline and select the vertical ⋮ > Run.

    During this initial run, your pipeline is tested, and the following pipeline components are deployed to your project as workloads in a new namespace dedicated to the pipeline:

    • docker-registry
    • jenkins
    • minio

    This process takes several minutes. When it completes, you can view each pipeline component from the project Workloads tab.

    Triggering a Pipeline​

    When a repository is enabled, a webhook is automatically set in the version control provider. By default, the pipeline is triggered by a push event to a repository, but you can modify the event(s) that trigger running the pipeline.

    Available Events:

    • Push: Whenever a commit is pushed to the branch in the repository, the pipeline is triggered.
    • Pull Request: Whenever a pull request is made to the repository, the pipeline is triggered.
    • Tag: When a tag is created in the repository, the pipeline is triggered.
    note

    This option doesn't exist for Rancher's example repositories.

    Modifying the Event Triggers for the Repository​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.
    5. Find the repository where you want to modify the event triggers. Select the vertical ⋮ > Setting.
    6. Select which event triggers (Push, Pull Request or Tag) you want for the repository.
    7. Click Save.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/prometheus-federator-guides.html b/pages-for-subheaders/prometheus-federator-guides.html index 1b87c75034b..ccd180fb8c0 100644 --- a/pages-for-subheaders/prometheus-federator-guides.html +++ b/pages-for-subheaders/prometheus-federator-guides.html @@ -5,13 +5,13 @@ Prometheus Federator Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/prometheus-federator.html b/pages-for-subheaders/prometheus-federator.html index 1f5e6659b2d..80e56060a3e 100644 --- a/pages-for-subheaders/prometheus-federator.html +++ b/pages-for-subheaders/prometheus-federator.html @@ -5,13 +5,13 @@ Prometheus Federator | Rancher Manager - +
    Version: v2.6

    Prometheus Federator

    Prometheus Federator, also referred to as Project Monitoring v2, deploys a Helm Project Operator (based on the rancher/helm-project-operator), an operator that manages deploying Helm charts each containing a Project Monitoring Stack, where each stack contains:

    Important:

    Prometheus Federator is designed to be deployed alongside an existing Prometheus Operator deployment in a cluster that has already installed the Prometheus Operator CRDs.

    How does the operator work?​

    1. On deploying this chart, users can create ProjectHelmCharts CRs with spec.helmApiVersion set to monitoring.cattle.io/v1alpha1 (also known as "Project Monitors" in the Rancher UI) in a Project Registration Namespace (cattle-project-<id>).
    2. On seeing each ProjectHelmChartCR, the operator will automatically deploy a Project Prometheus stack on the Project Owner's behalf in the Project Release Namespace (cattle-project-<id>-monitoring) based on a HelmChart CR and a HelmRelease CR automatically created by the ProjectHelmChart controller in the Operator / System Namespace.
    3. RBAC will automatically be assigned in the Project Release Namespace to allow users to view the Prometheus, Alertmanager, and Grafana UIs of the Project Monitoring Stack deployed; this will be based on RBAC defined on the Project Registration Namespace against the default Kubernetes user-facing roles. For more information, see the section on configuring RBAC.

    What is a Project?​

    In Prometheus Federator, a Project is a group of namespaces that can be identified by a metav1.LabelSelector. By default, the label used to identify projects is field.cattle.io/projectId, the label used to identify namespaces that are contained within a given Rancher Project.

    Configuring the Helm release created by a ProjectHelmChart​

    The spec.values of this ProjectHelmChart's resources will correspond to the values.yaml override to be supplied to the underlying Helm chart deployed by the operator on the user's behalf; to see the underlying chart's values.yaml spec, either:

    • View the chart's definition located at rancher/prometheus-federator under charts/rancher-project-monitoring (where the chart version will be tied to the version of this operator).
    • Look for the ConfigMap named monitoring.cattle.io.v1alpha1 that is automatically created in each Project Registration Namespace, which will contain both the values.yaml and questions.yaml that was used to configure the chart (which was embedded directly into the prometheus-federator binary).

    Namespaces​

    As a Project Operator based on rancher/helm-project-operator, Prometheus Federator has three different classifications of namespaces that the operator looks out for:

    1. Operator / System Namespace: The namespace that the operator is deployed into (e.g., cattle-monitoring-system). This namespace will contain all HelmCharts and HelmReleases for all ProjectHelmCharts watched by this operator. Only Cluster Admins should have access to this namespace.

    2. Project Registration Namespace (cattle-project-<id>): The set of namespaces that the operator watches for ProjectHelmCharts within. The RoleBindings and ClusterRoleBindings that apply to this namespace will also be the source of truth for the auto-assigned RBAC created in the Project Release Namespace. For details, refer to the RBAC page. Project Owners (admin), Project Members (edit), and Read-Only Members (view) should have access to this namespace.

      Notes:

      • Project Registration Namespaces will be auto-generated by the operator and imported into the Project it is tied to if .Values.global.cattle.projectLabel is provided, which is set to field.cattle.io/projectId by default. This indicates that a Project Registration Namespace should be created by the operator if at least one namespace is observed with that label. The operator will not let these namespaces be deleted unless either all namespaces with that label are gone (e.g., this is the last namespace in that project, in which case the namespace will be marked with the label "helm.cattle.io/helm-project-operator-orphaned": "true", which signals that it can be deleted), or it is no longer watching that project because the project ID was provided under .Values.helmProjectOperator.otherSystemProjectLabelValues, which serves as a denylist for Projects. These namespaces will also never be auto-deleted to avoid destroying user data; it is recommended that users clean up these namespaces manually if desired on creating or deleting a project.

      • If .Values.global.cattle.projectLabel is not provided, the Operator / System Namespace will also be the Project Registration Namespace.

    3. Project Release Namespace (cattle-project-<id>-monitoring): The set of namespaces that the operator deploys Project Monitoring Stacks within on behalf of a ProjectHelmChart; the operator will also automatically assign RBAC to Roles created in this namespace by the Project Monitoring Stack based on bindings found in the Project Registration Namespace. Only Cluster Admins should have access to this namespace; Project Owners (admin), Project Members (edit), and Read-Only Members (view) will be assigned limited access to this namespace by the deployed Helm Chart and Prometheus Federator.

      Notes:

      • Project Release Namespaces are automatically deployed and imported into the project whose ID is specified under .Values.helmProjectOperator.projectReleaseNamespaces.labelValue, which defaults to the value of .Values.global.cattle.systemProjectId if not specified, whenever a ProjectHelmChart is specified in a Project Registration Namespace.

      • Project Release Namespaces follow the same orphaning conventions as Project Registration Namespaces (see note above).

      • If .Values.projectReleaseNamespaces.enabled is false, the Project Release Namespace will be the same as the Project Registration Namespace.

    Helm Resources (HelmChart, HelmRelease)​

    On deploying a ProjectHelmChart, the Prometheus Federator will automatically create and manage two child custom resources that manage the underlying Helm resources in turn:

    • A HelmChart CR (managed via an embedded k3s-io/helm-contoller in the operator): This custom resource automatically creates a Job in the same namespace that triggers a helm install, helm upgrade, or helm uninstall depending on the change applied to the HelmChart CR. This CR is automatically updated on changes to the ProjectHelmChart (e.g., modifying the values.yaml) or changes to the underlying Project definition (e.g., adding or removing namespaces from a project).
    Important:

    If a ProjectHelmChart is not deploying or updating the underlying Project Monitoring Stack for some reason, the Job created by this resource in the Operator / System namespace should be the first place you check to see if there's something wrong with the Helm operation. However, this is generally only accessible by a Cluster Admin.

    • A HelmRelease CR (managed via an embedded rancher/helm-locker in the operator): This custom resource automatically locks a deployed Helm release in place and automatically overwrites updates to underlying resources unless the change happens via a Helm operation (helm install, helm upgrade, or helm uninstall performed by the HelmChart CR).
    note

    HelmRelease CRs emit Kubernetes Events that detect when an underlying Helm release is being modified and locks it back to place. To view these events, you can use kubectl describe helmrelease <helm-release-name> -n <operator/system-namespace>; you can also view the logs on this operator to see when changes are detected and which resources modifications were attempted on.

    Both of these resources are created for all Helm charts in the Operator / System namespaces to avoid escalation of privileges to underprivileged users.

    Advanced Helm Project Operator Configuration​

    For more information on advanced configurations, refer to this page.

    Prometheus Federator on the Local Cluster​

    Prometheus Federator is a resource intensive application. Installing it to the local cluster is possible, but not recommended.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/provisioning-storage-examples.html b/pages-for-subheaders/provisioning-storage-examples.html index effbf5b484c..b1362d57b33 100644 --- a/pages-for-subheaders/provisioning-storage-examples.html +++ b/pages-for-subheaders/provisioning-storage-examples.html @@ -5,13 +5,13 @@ Provisioning Storage Examples | Rancher Manager - +
    Version: v2.6

    Provisioning Storage Examples

    Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself.

    For your convenience, Rancher offers documentation on how to configure some of the popular storage methods:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/quick-start-guides.html b/pages-for-subheaders/quick-start-guides.html index 51a6088ebac..3bd005f1bcd 100644 --- a/pages-for-subheaders/quick-start-guides.html +++ b/pages-for-subheaders/quick-start-guides.html @@ -5,13 +5,13 @@ Rancher Deployment Quick Start Guides | Rancher Manager - +
    Version: v2.6

    Rancher Deployment Quick Start Guides

    caution

    The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

    Use this section of the docs to jump start your deployment and testing of Rancher 2.x. It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future.

    We have Quick Start Guides for:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-behind-an-http-proxy.html b/pages-for-subheaders/rancher-behind-an-http-proxy.html index 63802bf209f..06a25141718 100644 --- a/pages-for-subheaders/rancher-behind-an-http-proxy.html +++ b/pages-for-subheaders/rancher-behind-an-http-proxy.html @@ -5,13 +5,13 @@ Installing Rancher behind an HTTP Proxy | Rancher Manager - +
    Version: v2.6

    Installing Rancher behind an HTTP Proxy

    In a lot of enterprise environments, servers or VMs running on premise do not have direct Internet access, but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to set up a highly available Rancher installation in such an environment.

    Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the Rancher docs.

    Installation Outline

    1. Set up infrastructure
    2. Set up a Kubernetes cluster
    3. Install Rancher
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-managed-clusters.html b/pages-for-subheaders/rancher-managed-clusters.html index 27162f41e14..c76a1639073 100644 --- a/pages-for-subheaders/rancher-managed-clusters.html +++ b/pages-for-subheaders/rancher-managed-clusters.html @@ -5,13 +5,13 @@ Best Practices for Rancher Managed Clusters | Rancher Manager - +
    Version: v2.6

    Best Practices for Rancher Managed Clusters

    Logging​

    Refer to this guide for our recommendations for cluster-level logging and application logging.

    Monitoring​

    Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. Refer to this guide for our recommendations.

    Tips for Setting Up Containers​

    Running well-built containers can greatly impact the overall performance and security of your environment. Refer to this guide for tips.

    Best Practices for Rancher Managed vSphere Clusters​

    This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-manager-architecture.html b/pages-for-subheaders/rancher-manager-architecture.html index fa2bc1d4796..816d456119e 100644 --- a/pages-for-subheaders/rancher-manager-architecture.html +++ b/pages-for-subheaders/rancher-manager-architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
    Version: v2.6

    Architecture

    This section focuses on the Rancher server and its components and how Rancher communicates with downstream Kubernetes clusters.

    For information on the different ways that Rancher can be installed, refer to the overview of installation options.

    For a list of main features of the Rancher API server, refer to the overview section.

    For guidance about setting up the underlying infrastructure for the Rancher server, refer to the architecture recommendations.

    note

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-on-a-single-node-with-docker.html b/pages-for-subheaders/rancher-on-a-single-node-with-docker.html index e5be403e67d..a70962399c0 100644 --- a/pages-for-subheaders/rancher-on-a-single-node-with-docker.html +++ b/pages-for-subheaders/rancher-on-a-single-node-with-docker.html @@ -5,13 +5,13 @@ Installing Rancher on a Single Node Using Docker | Rancher Manager - +
    Version: v2.6

    Installing Rancher on a Single Node Using Docker

    Rancher can be installed by running a single Docker container.

    In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.

    Want to use an external load balancer?

    See Docker Install with an External Load Balancer instead.

    A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Privileged Access for Rancher​

    When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the --privileged option.

    Requirements for OS, Docker, Hardware, and Networking

    Make sure that your node fulfills the general installation requirements.

    1. Provision Linux Host

    Provision a single Linux host according to our Requirements to launch your Rancher server.

    2. Choose an SSL Option and Install Rancher

    For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

    Do you want to..

    Choose from the following options:

    Option A: Default Rancher-generated Self-signed Certificate​

    If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

    Log into your host, and run the command below:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest

    Option B: Bring Your Own Certificate, Self-signed​

    In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.

    Prerequisites:

    Create a self-signed certificate using OpenSSL or another method of your choice.

    • The certificate files must be in PEM format.
    • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    After creating your certificate, run the Docker command below to install Rancher. Use the -v flag and provide the path to your certificates to mount them in your container.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <CA_CERTS.pem>The path to the certificate authority's certificate.

    Log into your host, and run the command below:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
      --privileged \
      rancher/rancher:latest

    Option C: Bring Your Own Certificate, Signed by a Recognized CA​

    In production environments where you're exposing an app publicly, you would use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.

    The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

    Prerequisites:
    • The certificate files must be in PEM format.
    • In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    After obtaining your certificate, run the Docker command below.

    • Use the -v flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
    • Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.
    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.

    Log into your host, and run the command below:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      --privileged \
      rancher/rancher:latest \
      --no-cacerts

    Option D: Let's Encrypt Certificate​

    caution

    Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

    For production environments, you also have the option of using Let's Encrypt certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, rancher.mydomain.com) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.

    The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

    Prerequisites:
    • Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
    • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
    • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.

    After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command.

    PlaceholderDescription
    <YOUR.DNS.NAME>Your domain address

    Log into your host, and run the command below:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest \
      --acme-domain <YOUR.DNS.NAME>

    Option E: Localhost tunneling, no Certificate​

    If you are installing Rancher in a development or testing environment where you have a localhost tunneling solution running, such as ngrok, avoid generating a certificate. This installation option doesn't require a certificate.

    • You will use --no-cacerts in the argument to disable the default CA certificate generated by Rancher.

    Log into your host, and run the command below:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest \
      --no-cacerts

    Advanced Options​

    When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:

    • Custom CA Certificate
    • API Audit Log
    • TLS Settings
    • Air Gap
    • Persistent Data
    • Running rancher/rancher and rancher/rancher-agent on the Same Node

    Refer to this page for details.

    Troubleshooting​

    Refer to this page for frequently asked questions and troubleshooting tips.

    What's Next?​

    • Recommended: Review Single Node Backup and Restore. Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
    • Create a Kubernetes cluster: Provisioning Kubernetes Clusters.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-security.html b/pages-for-subheaders/rancher-security.html index ed90e538f52..3e2d758ccd0 100644 --- a/pages-for-subheaders/rancher-security.html +++ b/pages-for-subheaders/rancher-security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
    Version: v2.6

    Security

    Security policy

    Rancher Labs supports responsible disclosure, and endeavours to resolve all issues in a reasonable time frame.

    Reporting process

    Please submit possible security issues by emailing security-rancher@suse.com .

    Announcements

    Subscribe to the Rancher announcements forum for release updates.

    Security is at the heart of all Rancher features. From integrating with all the popular authentication tools and services, to an enterprise grade RBAC capability, Rancher makes your Kubernetes clusters even more secure.

    On this page, we provide security related documentation along with resources to help you secure your Rancher installation and your downstream Kubernetes clusters.

    NeuVector Integration with Rancher​

    New in v2.6.5

    NeuVector is an open-source, container-focused security application that is now integrated into Rancher. NeuVector provides production security, DevOps vulnerability protection, and a container firewall, et al. Please see the Rancher docs and the NeuVector docs for more information.

    Running a CIS Security Scan on a Kubernetes Cluster​

    Rancher leverages kube-bench to run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS (Center for Internet Security) Kubernetes Benchmark.

    The CIS Kubernetes Benchmark is a reference document that can be used to establish a secure configuration baseline for Kubernetes.

    The Center for Internet Security (CIS) is a 501(c)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace".

    CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.

    The Benchmark provides recommendations of two types: Automated and Manual. We run tests related to only Automated recommendations.

    When Rancher runs a CIS security scan on a cluster, it generates a report showing the results of each test, including a summary with the number of passed, skipped and failed tests. The report also includes remediation steps for any failed tests.

    For details, refer to the section on security scans.

    SELinux RPM​

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8.

    We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: rancher-selinux and rke2-selinux. For details, see this page.

    Rancher Hardening Guide​

    The Rancher Hardening Guide is based on controls and best practices found in the CIS Kubernetes Benchmark from the Center for Internet Security.

    The hardening guides provide prescriptive guidance for hardening a production installation of Rancher. See Rancher's guides for Self Assessment of the CIS Kubernetes Benchmark for the full list of security controls.

    The hardening guides describe how to secure the nodes in your cluster, and it is recommended to follow a hardening guide before installing Kubernetes.

    Each version of the hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher.

    The CIS Benchmark and Self-Assessment​

    The benchmark self-assessment is a companion to the Rancher security hardening guide. While the hardening guide shows you how to harden the cluster, the benchmark guide is meant to help you evaluate the level of security of the hardened cluster.

    Because Rancher and RKE install Kubernetes services as Docker containers, many of the control verification checks in the CIS Kubernetes Benchmark don't apply. This guide will walk through the various controls and provide updated example commands to audit compliance in Rancher created clusters. The original benchmark documents can be downloaded from the CIS website.

    Each version of Rancher's self-assessment guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark.

    Third-party Penetration Test Reports​

    Rancher periodically hires third parties to perform security audits and penetration tests of the Rancher 2.x software stack. The environments under test follow the Rancher provided hardening guides at the time of the testing. Results are posted when the third party has also verified fixes classified MEDIUM or above.

    Results:

    Rancher Security Advisories and CVEs​

    Rancher is committed to informing the community of security issues in our products. For the list of CVEs (Common Vulnerabilities and Exposures) for issues we have resolved, refer to this page.

    Kubernetes Security Best Practices​

    For recommendations on securing your Kubernetes cluster, refer to the Kubernetes Security Best Practices guide.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-server-configuration.html b/pages-for-subheaders/rancher-server-configuration.html index df48df7afb0..058dfe3166d 100644 --- a/pages-for-subheaders/rancher-server-configuration.html +++ b/pages-for-subheaders/rancher-server-configuration.html @@ -5,13 +5,13 @@ Rancher Server Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-server.html b/pages-for-subheaders/rancher-server.html index 576bf2ce966..8ce291e877b 100644 --- a/pages-for-subheaders/rancher-server.html +++ b/pages-for-subheaders/rancher-server.html @@ -5,13 +5,13 @@ Best Practices for the Rancher Server | Rancher Manager - +
    Version: v2.6

    Best Practices for the Rancher Server

    This guide contains our recommendations for running the Rancher server, and is intended to be used in situations in which Rancher manages downstream Kubernetes clusters.

    Refer to this guide for our general advice for setting up the Rancher server on a high-availability Kubernetes cluster.

    Deployment Strategies​

    This guide is designed to help you choose whether a regional deployment strategy or a hub-and-spoke deployment strategy is better for a Rancher server that manages downstream Kubernetes clusters.

    Installing Rancher in a vSphere Environment​

    This guide outlines a reference architecture for installing Rancher in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/rancher-v2.6-hardening-guides.html b/pages-for-subheaders/rancher-v2.6-hardening-guides.html index a3c37f90894..12b96a68e9a 100644 --- a/pages-for-subheaders/rancher-v2.6-hardening-guides.html +++ b/pages-for-subheaders/rancher-v2.6-hardening-guides.html @@ -5,13 +5,13 @@ Self-Assessment and Hardening Guides for Rancher v2.6 | Rancher Manager - +
    Version: v2.6

    Self-Assessment and Hardening Guides for Rancher v2.6

    Rancher provides specific security hardening guides for each supported Rancher's Kubernetes distributions.

    Rancher Kubernetes Distributions​

    Rancher uses the following Kubernetes distributions:

    • RKE, Rancher Kubernetes Engine, is a CNCF-certified Kubernetes distribution that runs entirely within Docker containers.
    • RKE2 is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.
    • K3s is a fully conformant, lightweight Kubernetes distribution. It is easy to install, with half the memory of upstream Kubernetes, all in a binary of less than 100 MB.

    To harden a Kubernetes cluster outside of Rancher's distributions, refer to your Kubernetes provider docs.

    Hardening Guides and Benchmark Versions​

    These guides have been tested along with the Rancher v2.6 release. Each self-assessment guide is accompanied with a hardening guide and tested on a specific Kubernetes version and CIS benchmark version. If a CIS benchmark has not been validated for your Kubernetes version, you can choose to use the existing guides until a newer version is added.

    RKE Guides​

    Kubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guides
    Kubernetes v1.18 up to v1.23CIS v1.6LinkLink
    note
    • CIS v1.20 benchmark version for Kubernetes v1.19 and v1.20 is not yet released as a profile in Rancher's CIS Benchmark chart.

    RKE2 Guides​

    TypeKubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guides
    Rancher provisioned RKE2 clusterKubernetes v1.21 up to v1.23CIS v1.6LinkLink
    Standalone RKE2Kubernetes v1.21 up to v1.23CIS v1.6LinkLink

    K3s Guides​

    Kubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guides
    Kubernetes v1.21 and v1.22CIS v1.6LinkLink

    Rancher with SELinux​

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on RHEL and CentOS.

    To use Rancher with SELinux, we recommend installing the rancher-selinux RPM according to the instructions on this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/resources.html b/pages-for-subheaders/resources.html index 4159e7766ae..422e097d6dc 100644 --- a/pages-for-subheaders/resources.html +++ b/pages-for-subheaders/resources.html @@ -5,13 +5,13 @@ Resources | Rancher Manager - +
    Version: v2.6

    Resources

    Docker Installations​

    The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

    Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    Air-Gapped Installations​

    Follow these steps to install the Rancher server in an air gapped environment.

    An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Advanced Options​

    When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/selinux-rpm.html b/pages-for-subheaders/selinux-rpm.html index 8b8a9a52532..ca860382f8b 100644 --- a/pages-for-subheaders/selinux-rpm.html +++ b/pages-for-subheaders/selinux-rpm.html @@ -5,13 +5,13 @@ SELinux RPM | Rancher Manager - +
    Version: v2.6

    SELinux RPM

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux.

    Developed by Red Hat, it is an implementation of mandatory access controls (MAC) on Linux. Mandatory access controls allow an administrator of a system to define how applications and users can access different resources such as files, devices, networks and inter-process communication. SELinux also enhances security by making an OS restrictive by default.

    After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. To check whether SELinux is enabled and enforcing on your system, use getenforce:

    # getenforce
    Enforcing

    We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: rancher-selinux and rke2-selinux.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/set-up-cloud-providers.html b/pages-for-subheaders/set-up-cloud-providers.html index 2c8dc252f21..ee58d8320cc 100644 --- a/pages-for-subheaders/set-up-cloud-providers.html +++ b/pages-for-subheaders/set-up-cloud-providers.html @@ -5,13 +5,13 @@ Setting up Cloud Providers | Rancher Manager - +
    Version: v2.6

    Setting up Cloud Providers

    A cloud provider is a module in Kubernetes that provides an interface for managing nodes, load balancers, and networking routes.

    When a cloud provider is set up in Rancher, the Rancher server can automatically provision new nodes, load balancers or persistent storage devices when launching Kubernetes definitions, if the cloud provider you're using supports such automation.

    Your cluster will not provision correctly if you configure a cloud provider cluster of nodes that do not meet the prerequisites.

    By default, the Cloud Provider option is set to None.

    The following cloud providers can be enabled:

    • Amazon
    • Azure
    • GCE (Google Compute Engine)
    • vSphere

    Setting up the Amazon Cloud Provider​

    For details on enabling the Amazon cloud provider, refer to this page.

    Setting up the Azure Cloud Provider​

    For details on enabling the Azure cloud provider, refer to this page.

    Setting up the GCE Cloud Provider​

    For details on enabling the Google Compute Engine cloud provider, refer to this page.

    Setting up the vSphere Cloud Provider​

    For details on enabling the vSphere cloud provider, refer to this page.

    Setting up a Custom Cloud Provider​

    The Custom cloud provider is available if you want to configure any Kubernetes cloud provider.

    For the custom cloud provider option, you can refer to the RKE docs on how to edit the yaml file for your specific cloud provider. There are specific cloud providers that have more detailed configuration:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html b/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html index a8f8d0d212b..676eb70db48 100644 --- a/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html +++ b/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html @@ -5,13 +5,13 @@ Setting up Clusters from Hosted Kubernetes Providers | Rancher Manager - +
    Version: v2.6

    Setting up Clusters from Hosted Kubernetes Providers

    In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

    In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-prem or in an infrastructure provider.

    Rancher supports the following Kubernetes providers:

    Hosted Kubernetes Provider Authentication​

    When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/single-node-rancher-in-docker.html b/pages-for-subheaders/single-node-rancher-in-docker.html index 459da196289..29e14ea2d94 100644 --- a/pages-for-subheaders/single-node-rancher-in-docker.html +++ b/pages-for-subheaders/single-node-rancher-in-docker.html @@ -5,13 +5,13 @@ Single Node Rancher in Docker | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/use-existing-nodes.html b/pages-for-subheaders/use-existing-nodes.html index f6142e9a610..ba899846a19 100644 --- a/pages-for-subheaders/use-existing-nodes.html +++ b/pages-for-subheaders/use-existing-nodes.html @@ -5,13 +5,13 @@ Launching Kubernetes on Existing Custom Nodes | Rancher Manager - +
    Version: v2.6

    Launching Kubernetes on Existing Custom Nodes

    When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to create a Kubernetes cluster in on-prem bare-metal servers, on-prem virtual machines, or in any node hosted by an infrastructure provider.

    To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to the requirements, which includes some hardware specifications and Docker. After you install Docker on each server, you willl also run the command provided in the Rancher UI on each server to turn each one into a Kubernetes node.

    This section describes how to set up a custom cluster.

    Creating a Cluster with Custom Nodes

    Want to use Windows hosts as Kubernetes workers?

    See Configuring Custom Clusters for Windows before you start.

    1. Provision a Linux Host​

    Begin creation of a custom cluster by provisioning a Linux host. Your host can be:

    • A cloud-host virtual machine (VM)
    • An on-prem VM
    • A bare-metal server

    If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

    Provision the host according to the installation requirements and the checklist for production-ready clusters.

    If you're using Amazon EC2 as your host and want to use the dual-stack feature, there are additional requirements when provisioning the host.

    2. Create the Custom Cluster​

    1. Click ☰ > Cluster Management.

    2. On the Clusters page, click Create.

    3. Click Custom.

    4. Enter a Cluster Name.

    5. Use Cluster Configuration section to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options.

      Using Windows nodes as Kubernetes workers?
      Dual-stack on Amazon EC2:

      If you're using Amazon EC2 as your host and want to use the dual-stack feature, there are additional requirements when configuring RKE.

    6. Click Next.

    7. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    8. From Node Role, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: etcd, worker, and control plane. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see this section.

    note
    • Using Windows nodes as Kubernetes workers? See this section.
    • Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers).

    1. Optional: Click Show advanced options to specify IP address(es) to use when registering the node, override the hostname of the node, or to add labels or taints to the node.

    2. Copy the command displayed on screen to your clipboard.

    3. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

    note

    Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed.

    1. When you finish running the command(s) on your Linux host(s), click Done.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    3. Amazon Only: Tag Resources​

    If you have configured your cluster to use Amazon as Cloud Provider, tag your AWS resources with a cluster ID.

    Amazon Documentation: Tagging Your Amazon EC2 Resources

    note

    You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see Kubernetes Cloud Providers

    The following resources need to be tagged with a ClusterID:

    • Nodes: All hosts added in Rancher.
    • Subnet: The subnet used for your cluster
    • Security Group: The security group used for your cluster.
    note

    Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer.

    The tag that should be used is:

    Key=kubernetes.io/cluster/<CLUSTERID>, Value=owned

    <CLUSTERID> can be any string you choose. However, the same string must be used on every resource you tag. Setting the tag value to owned informs the cluster that all resources tagged with the <CLUSTERID> are owned and managed by this cluster.

    If you share resources between clusters, you can change the tag to:

    Key=kubernetes.io/cluster/CLUSTERID, Value=shared

    Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html b/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html index bc8cf347e44..c179f6cdaf7 100644 --- a/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html +++ b/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html @@ -5,13 +5,13 @@ Launching Kubernetes on New Nodes in an Infrastructure Provider | Rancher Manager - +
    Version: v2.6

    Launching Kubernetes on New Nodes in an Infrastructure Provider

    When you create an RKE or RKE2 cluster using a node template in Rancher, each resulting node pool is shown in a new Machine Pools tab. You can see the machine pools by doing the following:

    1. Click ☰ > Cluster Management.
    2. Click the name of the RKE or RKE2 cluster.

    RKE Clusters​

    Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers.

    One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

    The available cloud providers to create a node template are decided based on active node drivers.

    Node Templates​

    A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses Docker Machine to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher.

    After you create a node template in Rancher, it's saved so that you can use this template again to create node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile.

    Node Labels​

    You can add labels on each node template, so that any nodes created from the node template will automatically have these labels on them.

    Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.

    Node Taints​

    You can add taints on each node template, so that any nodes created from the node template will automatically have these taints on them.

    Since taints can be added at a node template and node pool, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

    Administrator Control of Node Templates​

    Administrators can control all node templates. Admins can now maintain all the node templates within Rancher. When a node template owner is no longer using Rancher, the node templates created by them can be managed by administrators so the cluster can continue to be updated and maintained.

    To access all node templates, an administrator will need to do the following:

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.

    Result: All node templates are listed. The templates can be edited or cloned by clicking the ⋮.

    Node Pools​

    Using Rancher, you can create pools of nodes based on a node template.

    A node template defines the configuration of a node, like what operating system to use, number of CPUs, and amount of memory.

    The benefit of using a node pool is that if a node is destroyed or deleted, you can increase the number of live nodes to compensate for the node that was lost. The node pool helps you ensure that the count of the node pool is as expected.

    Each node pool must have one or more nodes roles assigned.

    Each node role (i.e. etcd, controlplane, and worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.

    The recommended setup is to have:

    • a node pool with the etcd node role and a count of three
    • a node pool with the controlplane node role and a count of at least two
    • a node pool with the worker node role and a count of at least two

    RKE1 downstream cluster nodes in an air-gapped environment:

    By default, Rancher tries to run the Docker Install script when provisioning RKE1 downstream cluster nodes, such as in vSphere. However, the Rancher Docker installation script would fail in air-gapped environments. To work around this issue, you may choose to skip installing Docker when creating a Node Template where Docker is pre-installed onto a VM image. You can accomplish this by selecting None in the dropdown list for Docker Install URL under Engine Options in the Rancher UI.

    **Engine Options Dropdown:**

    Engine Options Dropdown

    Node Pool Taints​

    If you haven't defined taints on your node template, you can add taints for each node pool. The benefit of adding taints at a node pool is beneficial over adding it at a node template is that you can swap out the node templates without worrying if the taint is on the node template.

    For each taint, they will automatically be added to any created node in the node pool. Therefore, if you add taints to a node pool that have existing nodes, the taints won't apply to existing nodes in the node pool, but any new node added into the node pool will get the taint.

    When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

    About Node Auto-replace​

    If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes.

    caution

    Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

    Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the --node-monitor-period flag of the kube-controller). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool.

    Enabling Node Auto-replace​

    When you create the node pool, you can specify the amount of time in minutes that Rancher will wait to replace an unresponsive node.

    1. In the form for creating or editing a cluster, go to the Node Pools section.
    2. Go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
    3. Fill out the rest of the form for creating or editing the cluster.

    Result: Node auto-replace is enabled for the node pool.

    Disabling Node Auto-replace​

    You can disable node auto-replace from the Rancher UI with the following steps:

    1. Click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to disable node auto-replace and click ⋮ > Edit Config.
    3. In the Node Pools section, go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter 0.
    4. Click Save.

    Result: Node auto-replace is disabled for the node pool.

    Cloud Credentials​

    Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits:

    • Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time.

    • After the cloud credential is created, it can be re-used to create additional node templates.

    • Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once.

    After cloud credentials are created, the user can start managing the cloud credentials that they created.

    Node Drivers​

    If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in node drivers and activate it, or you can add your own custom node driver.

    RKE2 Clusters​

    Rancher v2.6 introduces provisioning for RKE2 clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.

    note

    For RKE2 cluster templates, please refer to this page for additional information.

    Node Roles​

    The RKE2 CLI exposes two roles, server and agent, which represent the Kubernetes node-roles etcd + controlplane and worker respectively. With RKE2 integration in Rancher v2.6, RKE2 node pools can represent more fine-grained role assignments such that etcd and controlplane roles can be represented.

    The same functionality of using etcd, controlplane and worker nodes is possible in the RKE2 CLI by using flags and node tainting to control where workloads and the Kubernetes master were scheduled. The reason those roles were not implemented as first-class roles in the RKE2 CLI is that RKE2 is conceptualized as a set of raw building blocks that are best leveraged through an orchestration system such as Rancher.

    The implementation of the three node roles in Rancher means that Rancher managed RKE2 clusters are able to easily leverage all of the same architectural best practices that are recommended for RKE clusters.

    In our recommended cluster architecture, we outline how many nodes of each role clusters should have:

    • At least three nodes with the role etcd to survive losing one node
    • At least two nodes with the role controlplane for master component high availability
    • At least two nodes with the role worker for workload rescheduling upon node failure
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/use-windows-clusters.html b/pages-for-subheaders/use-windows-clusters.html index 8b87dc3a175..4b9fadf2a7d 100644 --- a/pages-for-subheaders/use-windows-clusters.html +++ b/pages-for-subheaders/use-windows-clusters.html @@ -5,13 +5,13 @@ Launching Kubernetes on Windows Clusters | Rancher Manager - +
    Version: v2.6

    Launching Kubernetes on Windows Clusters

    When provisioning a custom cluster using Rancher, Rancher uses RKE (the Rancher Kubernetes Engine) to install Kubernetes on your existing nodes.

    In a Windows cluster provisioned with Rancher, the cluster must contain both Linux and Windows nodes. The Kubernetes controlplane can only run on Linux nodes, and the Windows nodes can only have the worker role. Windows nodes can only be used for deploying workloads.

    Some other requirements for Windows clusters include:

    • You can only add Windows nodes to a cluster if Windows support is enabled when the cluster is created. Windows support cannot be enabled for existing clusters.
    • Kubernetes 1.15+ is required.
    • The Flannel network provider must be used.
    • Windows nodes must have 50 GB of disk space.

    For the full list of requirements, see this section.

    For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on supported functionality and limitations for using Kubernetes with Windows or the guide for scheduling Windows containers in Kubernetes.

    Changes in Rancher v2.6​

    Rancher v2.6 introduces provisioning for RKE2 clusters directly from the Rancher UI. RKE2, also known as RKE Government, is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.

    As of Rancher v2.6.5, provisioning for RKE2 is GA.

    RKE2 Windows​

    The RKE2 provisioning feature also includes installing RKE2 on Windows clusters. Windows features for RKE2 include:

    • Windows Containers with RKE2 powered by containerd
    • Added provisioning of Windows RKE2 custom clusters directly from the Rancher UI
    • Calico CNI for Windows RKE2 custom clusters
    • SAC releases of Windows Server (2004 and 20H2) are included in the technical preview

    Windows Support for RKE2 Custom Clusters requires choosing Calico as the CNI.

    note

    Rancher will allow Windows workload pods to deploy on both Windows and Linux worker nodes by default. When creating mixed clusters in RKE2, you must edit the nodeSelector in the chart to direct the pods to be placed onto a compatible Windows node. Refer to the Kubernetes documentation for more information on how to use nodeSelector to assign pods to nodes.

    New in Rancher v2.6.7

    • HostProcess containers in Windows RKE2 are supported in Kubernetes v1.24.1 and up. See the upstream documentation for more information.

    Requirements for Windows Clusters​

    The general node requirements for networking, operating systems, and Docker are the same as the node requirements for a Rancher installation.

    OS and Docker Requirements​

    Our support for Windows Server and Windows containers match the Microsoft official lifecycle for LTSC (Long-Term Servicing Channel) and SAC (Semi-Annual Channel).

    For the support lifecycle dates for Windows Server, see the Microsoft Documentation.

    Kubernetes Version​

    Kubernetes v1.15+ is required.

    If you are using Kubernetes v1.21 with Windows Server 20H2 Standard Core, the patch "2019-08 Servicing Stack Update for Windows Server" must be installed on the node.

    Node Requirements​

    The hosts in the cluster need to have at least:

    • 2 core CPUs
    • 5 GB memory
    • 50 GB disk space

    Rancher will not provision the node if the node does not meet these requirements.

    Networking Requirements​

    Before provisioning a new cluster, be sure that you have already installed Rancher on a device that accepts inbound network traffic. This is required in order for the cluster nodes to communicate with Rancher. If you have not already installed Rancher, please refer to the installation documentation before proceeding with this guide.

    Rancher only supports Windows using Flannel as the network provider.

    There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.

    For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

    For VXLAN (Overlay) networking, the KB4489899 hotfix must be installed. Most cloud-hosted VMs already have this hotfix.

    If you are configuring DHCP options sets for an AWS virtual private cloud, note that in the domain-name option field, only one domain name can be specified. According to the DHCP options documentation:

    note

    Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name.

    Rancher on vSphere with ESXi 6.7u2 and above​

    If you are using Rancher on VMware vSphere with ESXi 6.7u2 or later with Red Hat Enterprise Linux 8.3, CentOS 8.3, or SUSE Enterprise Linux 15 SP2 or later, it is necessary to disable the vmxnet3 virtual network adapter hardware offloading feature. Failure to do so will result in all network connections between pods on different cluster nodes to fail with timeout errors. All connections from Windows pods to critical services running on Linux nodes, such as CoreDNS, will fail as well. It is also possible that external connections may fail. This issue is the result of Linux distributions enabling the hardware offloading feature in vmxnet3 and a bug in the vmxnet3 hardware offloading feature that results in the discarding of packets for guest overlay traffic. To address this issue, it is necessary disable the vmxnet3 hardware offloading feature. This setting does not survive reboot, so it is necessary to disable on every boot. The recommended course of action is to create a systemd unit file at /etc/systemd/system/disable_hw_offloading.service, which disables the vmxnet3 hardware offloading feature on boot. A sample systemd unit file which disables the vmxnet3 hardware offloading feature is as follows. Note that <VM network interface> must be customized to the host vmxnet3 network interface, e.g., ens192:

    [Unit]
    Description=Disable vmxnet3 hardware offloading feature

    [Service]
    Type=oneshot
    ExecStart=ethtool -K <VM network interface> tx-udp_tnl-segmentation off
    ExecStart=ethtool -K <VM network interface> tx-udp_tnl-csum-segmentation off
    StandardOutput=journal

    [Install]
    WantedBy=multi-user.target

    Then set the appropriate permissions on the systemd unit file:

    chmod 0644 /etc/systemd/system/disable_hw_offloading.service

    Finally, enable the systemd service:

    systemctl enable disable_hw_offloading.service

    Architecture Requirements​

    The Kubernetes cluster management nodes (etcd and controlplane) must be run on Linux nodes.

    The worker nodes, which is where your workloads will be deployed on, will typically be Windows nodes, but there must be at least one worker node that is run on Linux in order to run the Rancher cluster agent, DNS, metrics server, and Ingress related containers.

    We recommend the minimum three-node architecture listed in the table below, but you can always add additional Linux and Windows workers to scale up your cluster for redundancy:

    NodeOperating SystemKubernetes Cluster Role(s)Purpose
    Node 1Linux (Ubuntu Server 18.04 recommended)Control plane, etcd, workerManage the Kubernetes cluster
    Node 2Linux (Ubuntu Server 18.04 recommended)WorkerSupport the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster
    Node 3Windows (Windows Server core version 1809 or above)WorkerRun your Windows containers

    Container Requirements​

    Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server core version 1809 or above. If you have existing containers built for an earlier Windows Server core version, they must be re-built on Windows Server core version 1809 or above.

    Cloud Provider Specific Requirements​

    If you set a Kubernetes cloud provider in your cluster, some additional steps are required. You might want to set a cloud provider if you want to want to leverage a cloud provider's capabilities, for example, to automatically provision storage, load balancers, or other infrastructure for your cluster. Refer to this page for details on how to configure a cloud provider cluster of nodes that meet the prerequisites.

    If you are using the GCE (Google Compute Engine) cloud provider, you must do the following:

    • Enable the GCE cloud provider in the cluster.yml by following these steps.
    • When provisioning the cluster in Rancher, choose Custom cloud provider as the cloud provider in the Rancher UI.

    Tutorial: How to Create a Cluster with Windows Support​

    This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the recommended architecture.

    When you provision a cluster with Rancher on existing nodes, you will add nodes to the cluster by installing the Rancher agent on each one. When you create or edit your cluster from the Rancher UI, you will see a Customize Node Run Command that you can run on each server to add it to your cluster.

    To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below.

    1. Provision Hosts​

    To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts.

    Your hosts can be:

    • Cloud-hosted VMs
    • VMs from virtualization clusters
    • Bare-metal servers

    You will provision three nodes:

    • One Linux node, which manages the Kubernetes control plane and stores your etcd
    • A second Linux node, which will be another worker node
    • The Windows node, which will run your Windows containers as a worker node
    NodeOperating System
    Node 1Linux (Ubuntu Server 18.04 recommended)
    Node 2Linux (Ubuntu Server 18.04 recommended)
    Node 3Windows (Windows Server core version 1809 or above required)

    If your nodes are hosted by a Cloud Provider and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see Selecting Cloud Providers.

    2. Create the Cluster on Existing Nodes​

    The instructions for creating a Windows cluster on existing nodes are very similar to the general instructions for creating a custom cluster with some Windows-specific requirements.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, click Create.
    3. Click Custom.
    4. Enter a name for your cluster in the Cluster Name field.
    5. In the Kubernetes Version dropdown menu, select v1.19 or above.
    6. In the Network Provider field, select Flannel.
    7. In the Windows Support section, click Enabled.
    8. Optional: After you enable Windows support, you will be able to choose the Flannel backend. There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.
    9. Click Next.
    Important:

    For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

    3. Add Nodes to the Cluster​

    This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node.

    Add Linux Master Node​

    In this section, we fill out a form on the Rancher UI to get a custom command to install the Rancher agent on the Linux master node. Then we will copy the command and run it on our Linux master node to register the node in the cluster.

    The first node in your cluster should be a Linux host has both the Control Plane and etcd roles. At a minimum, both of these roles must be enabled for this node, and this node must be added to your cluster before you can add Windows hosts.

    1. In the Node Operating System section, click Linux.
    2. In the Node Role section, choose at least etcd and Control Plane. We recommend selecting all three.
    3. Optional: If you click Show advanced options, you can customize the settings for the Rancher agent and node labels.
    4. Copy the command displayed on the screen to your clipboard.
    5. SSH into your Linux host and run the command that you copied to your clipboard.
    6. When you are finished provisioning your Linux node(s), select Done.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    It may take a few minutes for the node to be registered in your cluster.

    Add Linux Worker Node​

    In this section, we run a command to register the Linux worker node to the cluster.

    After the initial provisioning of your cluster, your cluster only has a single Linux host. Next, we add another Linux worker host, which will be used to support Rancher cluster agent, Metrics server, DNS and Ingress for your cluster.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that you created and click ⋮ > Edit Config.
    3. Scroll down to Node Operating System. Choose Linux.
    4. In the Customize Node Run Command section, go to the Node Options and select the Worker role.
    5. Copy the command displayed on screen to your clipboard.
    6. Log in to your Linux host using a remote Terminal connection. Run the command copied to your clipboard.
    7. From Rancher, click Save.

    Result: The Worker role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.

    note

    Taints on Linux Worker Nodes

    For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.

    Taint KeyTaint ValueTaint Effect
    cattle.io/oslinuxNoSchedule

    Add a Windows Worker Node​

    In this section, we run a command to register the Windows worker node to the cluster.

    You can add Windows hosts to the cluster by editing the cluster and choosing the Windows option.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster that you created and click ⋮ > Edit Config.
    3. Scroll down to Node Operating System. Choose Windows. Note: You will see that the worker role is the only available role.
    4. Copy the command displayed on screen to your clipboard.
    5. Log in to your Windows host using your preferred tool, such as Microsoft Remote Desktop. Run the command copied to your clipboard in the Command Prompt (CMD).
    6. From Rancher, click Save.
    7. Optional: Repeat these instructions if you want to add more Windows nodes to your cluster.

    Result: The Worker role is installed on your Windows host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster. You now have a Windows Kubernetes cluster.

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    Configuration for Storage Classes in Azure​

    If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster. For details, refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/user-settings.html b/pages-for-subheaders/user-settings.html index d1ba8a082ff..d6d09d40505 100644 --- a/pages-for-subheaders/user-settings.html +++ b/pages-for-subheaders/user-settings.html @@ -5,13 +5,13 @@ User Settings | Rancher Manager - +
    Version: v2.6

    User Settings

    Within Rancher, each user has a number of settings associated with their login: personal preferences, API keys, etc. You can configure these settings by choosing from the User Settings menu. You can open this menu by clicking your avatar, located within the main menu.

    User Settings Menu

    The available user settings are:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/vsphere-cloud-provider.html b/pages-for-subheaders/vsphere-cloud-provider.html index f06ee4ce451..9cc599ed38e 100644 --- a/pages-for-subheaders/vsphere-cloud-provider.html +++ b/pages-for-subheaders/vsphere-cloud-provider.html @@ -5,13 +5,13 @@ Setting up the vSphere Cloud Provider | Rancher Manager - +
    Version: v2.6

    Setting up the vSphere Cloud Provider

    In this section, you'll learn how to set up a vSphere cloud provider for a Rancher managed RKE Kubernetes cluster in vSphere.

    In-tree Cloud Provider

    To use the in-tree vSphere cloud provider, you will need to use an RKE configuration option. For details, refer to this page.

    Out-of-tree Cloud Provider

    To set up the out-of-tree vSphere cloud provider, you will need to install Helm charts from the Rancher marketplace. For details, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/vsphere.html b/pages-for-subheaders/vsphere.html index ee9984f26a4..3193b703393 100644 --- a/pages-for-subheaders/vsphere.html +++ b/pages-for-subheaders/vsphere.html @@ -5,13 +5,13 @@ Creating a vSphere Cluster | Rancher Manager - +
    Version: v2.6

    Creating a vSphere Cluster

    By using Rancher with vSphere, you can bring cloud operations on-premises.

    Rancher can provision nodes in vSphere and install Kubernetes on them. When creating a Kubernetes cluster in vSphere, Rancher first provisions the specified number of virtual machines by communicating with the vCenter API. Then it installs Kubernetes on top of them.

    A vSphere cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role.

    vSphere Enhancements in Rancher v2.3​

    The vSphere node templates have been updated, allowing you to bring cloud operations on-premises with the following enhancements:

    Self-healing Node Pools​

    One of the biggest advantages of provisioning vSphere nodes with Rancher is that it allows you to take advantage of Rancher's self-healing node pools, also called the node auto-replace feature, in your on-premises clusters. Self-healing node pools are designed to help you replace worker nodes for stateless applications. When Rancher provisions nodes from a node template, Rancher can automatically replace unreachable nodes.

    caution

    It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

    Dynamically Populated Options for Instances and Scheduling​

    Node templates for vSphere have been updated so that when you create a node template with your vSphere credentials, the template is automatically populated with the same options for provisioning VMs that you have access to in the vSphere console.

    For the fields to be populated, your setup needs to fulfill the prerequisites.

    More Supported Operating Systems​

    You can provision VMs with any operating system that supports cloud-init. Only YAML format is supported for the cloud config.

    Video Walkthrough of v2.3.3 Node Template Features​

    In this YouTube video, we demonstrate how to set up a node template with the new features designed to help you bring cloud operations to on-premises clusters.

    Creating a vSphere Cluster​

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

    Provisioning Storage​

    For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

    Enabling the vSphere Cloud Provider​

    When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices.

    For details, refer to the section on enabling the vSphere cloud provider.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/pages-for-subheaders/workloads-and-pods.html b/pages-for-subheaders/workloads-and-pods.html index 26cbac65c54..e6140325692 100644 --- a/pages-for-subheaders/workloads-and-pods.html +++ b/pages-for-subheaders/workloads-and-pods.html @@ -5,14 +5,14 @@ Kubernetes Workloads and Pods | Rancher Manager - +
    Version: v2.6

    Kubernetes Workloads and Pods

    You can build any complex containerized application in Kubernetes using two basic constructs: pods and workloads. Once you build an application, you can expose it for access either within the same cluster or on the Internet using a third construct: services.

    Pods​

    Pods are one or more containers that share network namespaces and storage volumes. Most pods have only one container. Therefore when we discuss pods, the term is often synonymous with containers. You scale pods the same way you scale containers—by having multiple instances of the same pod that implement a service. Usually pods get scaled and managed by the workload.

    Workloads​

    Workloads are objects that set deployment rules for pods. Based on these rules, Kubernetes performs the deployment and updates the workload with the current state of the application. Workloads let you define the rules for application scheduling, scaling, and upgrade.

    Workload Types​

    Kubernetes divides workloads into different types. The most popular types supported by Kubernetes are:

    • Deployments

      Deployments are best used for stateless applications (i.e., when you don't have to maintain the workload's state). Pods managed by deployment workloads are treated as independent and disposable. If a pod encounters disruption, Kubernetes removes it and then recreates it. An example application would be an Nginx web server.

    • StatefulSets

      StatefulSets, in contrast to deployments, are best used when your application needs to maintain its identity and store data. An application would be something like Zookeeper—an application that requires a database for storage.

    • DaemonSets

      Daemonsets ensures that every node in the cluster runs a copy of pod. For use cases where you're collecting logs or monitoring node performance, this daemon-like workload works best.

    • Jobs

      Jobs launch one or more pods and ensure that a specified number of them successfully terminate. Jobs are best used to run a finite task to completion as opposed to managing an ongoing desired application state.

    • CronJobs

      CronJobs are similar to jobs. CronJobs, however, runs to completion on a cron-based schedule.

    Services​

    In many use cases, a workload has to be either:

    • Accessed by other workloads in the cluster.
    • Exposed to the outside world.

    You can achieve these goals by creating a Service. Services are mapped to the underlying workload's pods using a selector/label approach (view the code samples). Rancher UI simplifies this mapping process by automatically creating a service along with the workload, using the service port and type that you select.

    Service Types​

    There are several types of services available in Rancher. The descriptions below are sourced from the Kubernetes Documentation.

    • ClusterIP

      Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default ServiceType.

    • NodePort

      Exposes the service on each Node’s IP at a static port (the NodePort). A ClusterIP service, to which the NodePort service will route, is automatically created. You’ll be able to contact the NodePort service, from outside the cluster, by requesting <NodeIP>:<NodePort>.

    • LoadBalancer

      Exposes the service externally using a cloud provider’s load balancer. NodePort and ClusterIP services, to which the external load balancer will route, are automatically created.

    Workload Options​

    This section of the documentation contains instructions for deploying workloads and using workload options.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides.html b/reference-guides.html index ea1185c501e..60bd574b028 100644 --- a/reference-guides.html +++ b/reference-guides.html @@ -5,13 +5,13 @@ Reference Guides | Rancher Manager - +
    Version: v2.6

    Reference Guides

    Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

    These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

    The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

    Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/about-the-api/api-tokens.html b/reference-guides/about-the-api/api-tokens.html index 07e4127a0a3..3c56d211c23 100644 --- a/reference-guides/about-the-api/api-tokens.html +++ b/reference-guides/about-the-api/api-tokens.html @@ -5,7 +5,7 @@ API Tokens | Rancher Manager - + @@ -14,7 +14,7 @@ Introduced in version 2.6.6.

    kubeconfig-token-ttl-minutes​

    Time to live (TTL) duration in minutes used to determine when a kubeconfig token that was generated by the CLI expires. Tokens are generated by the CLI when kubeconfig-generate-token is false. When the token is expired, the API will reject the token. This setting can not be larger than auth-token-max-ttl-minutes. Deprecated since version 2.6.6, and will be removed in 2.8.0: This setting will be replaced with the value of kubeconfig-default-token-TTL-minutes.

    auth-token-max-ttl-minutes​

    Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than auth-token-max-ttl-minutes, Rancher will set the token TTL to the value of auth-token-max-ttl-minutes. Auth tokens are tokens created for authenticating API requests. Changed in version 2.6.6: Applies to all kubeconfig tokens and api tokens.

    kubeconfig-generate-token​

    When true, kubeconfigs requested through the UI will contain a valid token. When false, the kubeconfig will contain a command that uses the Rancher CLI to prompt the user to log in. The CLI then will retrieve and cache a token for the user.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html b/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html index 0945a778712..c4b095478f9 100644 --- a/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html +++ b/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html @@ -5,13 +5,13 @@ Minimum EKS Permissions | Rancher Manager - +
    Version: v2.6

    Minimum EKS Permissions

    Documented here is a minimum set of permissions necessary to use all functionality of the EKS driver in Rancher. Additional permissions are required for Rancher to provision the Service Role and VPC resources. Optionally these resources can be created before the cluster creation and will be selectable when defining the cluster configuration.

    ResourceDescription
    Service RoleThe service role provides Kubernetes the permissions it requires to manage resources on your behalf. Rancher can create the service role with the following Service Role Permissions.
    VPCProvides isolated network resources utilised by EKS and worker nodes. Rancher can create the VPC resources with the following VPC Permissions.

    Resource targeting uses * as the ARN of many of the resources created cannot be known before creating the EKS cluster in Rancher.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "EC2Permisssions",
                "Effect": "Allow",
                "Action": [
                    "ec2:RunInstances",
                    "ec2:RevokeSecurityGroupIngress",
                    "ec2:RevokeSecurityGroupEgress",
                    "ec2:DescribeInstanceTypes",
                    "ec2:DescribeRegions",
                    "ec2:DescribeVpcs",
                    "ec2:DescribeTags",
                    "ec2:DescribeSubnets",
                    "ec2:DescribeSecurityGroups",
                    "ec2:DescribeRouteTables",
                    "ec2:DescribeLaunchTemplateVersions",
                    "ec2:DescribeLaunchTemplates",
                    "ec2:DescribeKeyPairs",
                    "ec2:DescribeInternetGateways",
                    "ec2:DescribeImages",
                    "ec2:DescribeAvailabilityZones",
                    "ec2:DescribeAccountAttributes",
                    "ec2:DeleteTags",
                    "ec2:DeleteSecurityGroup",
                    "ec2:DeleteKeyPair",
                    "ec2:CreateTags",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateLaunchTemplateVersion",
                    "ec2:CreateLaunchTemplate",
                    "ec2:CreateKeyPair",
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:AuthorizeSecurityGroupEgress"
                ],
                "Resource": "*"
            },
            {
                "Sid": "CloudFormationPermisssions",
                "Effect": "Allow",
                "Action": [
                    "cloudformation:ListStacks",
                    "cloudformation:ListStackResources",
                    "cloudformation:DescribeStacks",
                    "cloudformation:DescribeStackResources",
                    "cloudformation:DescribeStackResource",
                    "cloudformation:DeleteStack",
                    "cloudformation:CreateStackSet",
                    "cloudformation:CreateStack"
                ],
                "Resource": "*"
            },
            {
                "Sid": "IAMPermissions",
                "Effect": "Allow",
                "Action": [
                    "iam:PassRole",
                    "iam:ListRoles",
                    "iam:ListRoleTags",
                    "iam:ListInstanceProfilesForRole",
                    "iam:ListInstanceProfiles",
                    "iam:ListAttachedRolePolicies",
                    "iam:GetRole",
                    "iam:GetInstanceProfile",
                    "iam:DetachRolePolicy",
                    "iam:DeleteRole",
                    "iam:CreateRole",
                    "iam:AttachRolePolicy"
                ],
                "Resource": "*"
            },
            {
                "Sid": "KMSPermisssions",
                "Effect": "Allow",
                "Action": "kms:ListKeys",
                "Resource": "*"
            },
            {
                "Sid": "EKSPermisssions",
                "Effect": "Allow",
                "Action": [
                    "eks:UpdateNodegroupVersion",
                    "eks:UpdateNodegroupConfig",
                    "eks:UpdateClusterVersion",
                    "eks:UpdateClusterConfig",
                    "eks:UntagResource",
                    "eks:TagResource",
                    "eks:ListUpdates",
                    "eks:ListTagsForResource",
                    "eks:ListNodegroups",
                    "eks:ListFargateProfiles",
                    "eks:ListClusters",
                    "eks:DescribeUpdate",
                    "eks:DescribeNodegroup",
                    "eks:DescribeFargateProfile",
                    "eks:DescribeCluster",
                    "eks:DeleteNodegroup",
                    "eks:DeleteFargateProfile",
                    "eks:DeleteCluster",
                    "eks:CreateNodegroup",
                    "eks:CreateFargateProfile",
                    "eks:CreateCluster"
                ],
                "Resource": "*"
            }
        ]
    }

    Service Role Permissions​

    Permissions required for Rancher to create service role on users behalf during the EKS cluster creation process.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "IAMPermisssions",
          "Effect": "Allow",
          "Action": [
            "iam:AddRoleToInstanceProfile",
            "iam:AttachRolePolicy",
            "iam:CreateInstanceProfile",
            "iam:CreateRole",
            "iam:CreateServiceLinkedRole",
            "iam:DeleteInstanceProfile",
            "iam:DeleteRole",
            "iam:DetachRolePolicy",
            "iam:GetInstanceProfile",
            "iam:GetRole",
            "iam:ListAttachedRolePolicies",
            "iam:ListInstanceProfiles",
            "iam:ListInstanceProfilesForRole",
            "iam:ListRoles",
            "iam:ListRoleTags",
            "iam:PassRole",
            "iam:RemoveRoleFromInstanceProfile"
          ],
          "Resource": "*"
        }
      ]
    }

    When an EKS cluster is created, Rancher will create a service role with the following trust policy:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Principal": {
            "Service": "eks.amazonaws.com"
          },
          "Effect": "Allow",
          "Sid": ""
        }
      ]
    }

    This role will also have two role policy attachments with the following policies ARNs:

    arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
    arn:aws:iam::aws:policy/AmazonEKSServicePolicy

    VPC Permissions​

    Permissions required for Rancher to create VPC and associated resources.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "VPCPermissions",
          "Effect": "Allow",
          "Action": [
            "ec2:ReplaceRoute",
            "ec2:ModifyVpcAttribute",
            "ec2:ModifySubnetAttribute",
            "ec2:DisassociateRouteTable",
            "ec2:DetachInternetGateway",
            "ec2:DescribeVpcs",
            "ec2:DeleteVpc",
            "ec2:DeleteTags",
            "ec2:DeleteSubnet",
            "ec2:DeleteRouteTable",
            "ec2:DeleteRoute",
            "ec2:DeleteInternetGateway",
            "ec2:CreateVpc",
            "ec2:CreateSubnet",
            "ec2:CreateSecurityGroup",
            "ec2:CreateRouteTable",
            "ec2:CreateRoute",
            "ec2:CreateInternetGateway",
            "ec2:AttachInternetGateway",
            "ec2:AssociateRouteTable"
          ],
          "Resource": "*"
        }
      ]
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/backup-restore-configuration/backup-configuration.html b/reference-guides/backup-restore-configuration/backup-configuration.html index 3560ba02f1b..05070ccb66f 100644 --- a/reference-guides/backup-restore-configuration/backup-configuration.html +++ b/reference-guides/backup-restore-configuration/backup-configuration.html @@ -5,13 +5,13 @@ Backup Configuration | Rancher Manager - +
    -
    Version: v2.6

    Backup Configuration

    The Backup Create page lets you configure a schedule, enable encryption and specify the storage location for your backups.

    Schedule​

    Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting Recurring Backups lets you configure following two fields:

    • Schedule: This field accepts
      • Standard cron expressions, such as "0 * * * *"
      • Descriptors, such as "@midnight" or "@every 1h30m"
    • Retention Count: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10.
    YAML Directive NameDescription
    scheduleProvide the cron string for scheduling recurring backups.
    retentionCountProvide the number of backup files to be retained.

    Encryption​

    The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if encryption at rest is enabled, even the encrypted objects gathered by the backup will be in plaintext.

    To avoid storing them in plaintext, you can use the same EncryptionConfiguration file that was used for at rest encryption, to encrypt certain resources in your backup.

    Important:

    When encrypting objects in the backup you must save the EncryptionConfiguration file for future use, because it won’t be saved by the rancher-backup operator.

    For example, when migrating Rancher to a new cluster the file is used to re-create the secret in the new cluster.

    The operator consumes the EncryptionConfiguration as a Kubernetes Secret in the cattle-resources-system namespace under the key named encryption-provider-config.yaml in the secret data.

    For the EncryptionConfiguration, you can use the sample file provided in the Kubernetes documentation.

    To ensure the correct key is used in the secret, the encryption configuration file must be named encryption-provider-config.yaml. The below command uses the --from-file flag to create the secret with the correct key name.

    Save the EncryptionConfiguration in a file called encryption-provider-config.yaml and run this command:

    kubectl create secret generic encryptionconfig \
      --from-file=./encryption-provider-config.yaml \
      -n cattle-resources-system

    This will ensure that the secret contains a key named encryption-provider-config.yaml, and the operator will use this key to get the encryption configuration.

    The Encryption Config Secret dropdown will filter out and list only those Secrets that have this exact key.

    In the example command above, the name encryptionconfig can be changed to anything.

    YAML Directive NameDescription
    encryptionConfigSecretNameProvide the name of the Secret from cattle-resources-system namespace, that contains the encryption config file.

    Storage Location​

    If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the rancher-backup operator.

    Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup.

    S3​

    The S3 storage location contains the following configuration fields:

    1. Credential Secret (optional): If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section. The Credential Secret dropdown lists the secrets in all namespaces.
    2. Bucket Name: The name of the S3 bucket where backup files will be stored.
    3. Region (optional): The AWS region where the S3 bucket is located. This field isn't needed for configuring MinIO.
    4. Folder (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    5. Endpoint: The endpoint that is used to access S3 in the region of your bucket.
    6. Endpoint CA (optional): This should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    7. Skip TLS Verifications (optional): Set to true if you are not using TLS.
    YAML Directive NameDescriptionRequired
    credentialSecretNameIf you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace as long as you provide that namespace in credentialSecretNamespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    credentialSecretNamespaceThe namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    bucketNameThe name of the S3 bucket where backup files will be stored.✓
    folderThe name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    regionThe AWS region where the S3 bucket is located.✓
    endpointThe endpoint that is used to access S3 in the region of your bucket.✓
    endpointCAThis should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    insecureTLSSkipVerifySet to true if you are not using TLS.

    Example S3 Storage Configuration​

    s3:
      credentialSecretName: s3-creds
      credentialSecretNamespace: default
      bucketName: rancher-backups
      folder: rancher
      region: us-west-2
      endpoint: s3.us-west-2.amazonaws.com

    Example MinIO Configuration​

    s3:
      credentialSecretName: minio-creds
      bucketName: rancherbackups
      endpoint: minio.35.202.130.254.xip.io
      endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t

    Example credentialSecret​

    apiVersion: v1
    kind: Secret
    metadata:
      name: creds
    type: Opaque
    data:
      accessKey: <base64-encoded access key>
      secretKey: <base64-encoded secret key>
    note

    To avoid encoding issues, the credentialSecret can be created with the below command, updating the values for accessKey and secretKey.

    kubectl create secret generic s3-creds \
      --from-literal=accessKey=<access key> \
      --from-literal=secretKey=<secret key>

    IAM Permissions for EC2 Nodes to Access S3​

    There are two ways to set up the rancher-backup operator to use S3 as the backup storage location.

    One way is to configure the credentialSecretName in the Backup custom resource, which refers to AWS credentials that have access to S3.

    If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3.

    To allow a node to access S3, follow the instructions in the AWS documentation to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the Resource with your bucket name:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket"
          ],
         "Resource": [
            "arn:aws:s3:::rancher-backups"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:GetObject",
            "s3:DeleteObject",
            "s3:PutObjectAcl"
          ],
          "Resource": [
             "arn:aws:s3:::rancher-backups/*"
          ]
        }
      ]
    }

    After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the credentialSecretName directive can be left empty in the Backup custom resource.

    Examples​

    For example Backup custom resources, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - +
    Version: v2.6

    Backup Configuration

    The Backup Create page lets you configure a schedule, enable encryption and specify the storage location for your backups.

    Schedule​

    Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting Recurring Backups lets you configure following two fields:

    • Schedule: This field accepts
      • Standard cron expressions, such as "0 * * * *"
      • Descriptors, such as "@midnight" or "@every 1h30m"
    • Retention Count: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10.
    YAML Directive NameDescription
    scheduleProvide the cron string for scheduling recurring backups.
    retentionCountProvide the number of backup files to be retained.

    Encryption​

    The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if encryption at rest is enabled, even the encrypted objects gathered by the backup will be in plaintext.

    To avoid storing them in plaintext, you can use the same EncryptionConfiguration file that was used for at rest encryption, to encrypt certain resources in your backup.

    Important:

    When encrypting objects in the backup you must save the EncryptionConfiguration file for future use, because it won’t be saved by the rancher-backup operator.

    For example, when migrating Rancher to a new cluster the file is used to re-create the secret in the new cluster.

    The operator consumes the EncryptionConfiguration as a Kubernetes Secret in the cattle-resources-system namespace under the key named encryption-provider-config.yaml in the secret data.

    For the EncryptionConfiguration, you can use the sample file provided in the Kubernetes documentation.

    To ensure the correct key is used in the secret, the encryption configuration file must be named encryption-provider-config.yaml. The below command uses the --from-file flag to create the secret with the correct key name.

    Save the EncryptionConfiguration in a file called encryption-provider-config.yaml and run this command:

    kubectl create secret generic encryptionconfig \
      --from-file=./encryption-provider-config.yaml \
      -n cattle-resources-system

    This will ensure that the secret contains a key named encryption-provider-config.yaml, and the operator will use this key to get the encryption configuration.

    The Encryption Config Secret dropdown will filter out and list only those Secrets that have this exact key.

    In the example command above, the name encryptionconfig can be changed to anything.

    YAML Directive NameDescription
    encryptionConfigSecretNameProvide the name of the Secret from cattle-resources-system namespace, that contains the encryption config file.

    Storage Location​

    If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the rancher-backup operator.

    Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup.

    S3​

    The S3 storage location contains the following configuration fields:

    1. Credential Secret (optional): If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section. The Credential Secret dropdown lists the secrets in all namespaces.
    2. Bucket Name: The name of the S3 bucket where backup files will be stored.
    3. Region (optional): The AWS region where the S3 bucket is located. This field isn't needed for configuring MinIO.
    4. Folder (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    5. Endpoint: The endpoint that is used to access S3 in the region of your bucket.
    6. Endpoint CA (optional): This should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    7. Skip TLS Verifications (optional): Set to true if you are not using TLS.
    YAML Directive NameDescriptionRequired
    credentialSecretNameIf you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace as long as you provide that namespace in credentialSecretNamespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    credentialSecretNamespaceThe namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    bucketNameThe name of the S3 bucket where backup files will be stored.✓
    folderThe name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    regionThe AWS region where the S3 bucket is located.✓
    endpointThe endpoint that is used to access S3 in the region of your bucket.✓
    endpointCAThis should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    insecureTLSSkipVerifySet to true if you are not using TLS.

    Example S3 Storage Configuration​

    s3:
      credentialSecretName: s3-creds
      credentialSecretNamespace: default
      bucketName: rancher-backups
      folder: rancher
      region: us-west-2
      endpoint: s3.us-west-2.amazonaws.com

    Example MinIO Configuration​

    s3:
      credentialSecretName: minio-creds
      bucketName: rancherbackups
      endpoint: minio.35.202.130.254.xip.io
      endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t

    Example credentialSecret​

    apiVersion: v1
    kind: Secret
    metadata:
      name: creds
    type: Opaque
    data:
      accessKey: <base64-encoded access key>
      secretKey: <base64-encoded secret key>
    note

    To avoid encoding issues, the credentialSecret can be created with the below command, updating the values for accessKey and secretKey.

    kubectl create secret generic s3-creds \
      --from-literal=accessKey=<access key> \
      --from-literal=secretKey=<secret key>

    IAM Permissions for EC2 Nodes to Access S3​

    There are two ways to set up the rancher-backup operator to use S3 as the backup storage location.

    One way is to configure the credentialSecretName in the Backup custom resource, which refers to AWS credentials that have access to S3.

    If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3.

    To allow a node to access S3, follow the instructions in the AWS documentation to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the Resource with your bucket name:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket"
          ],
         "Resource": [
            "arn:aws:s3:::rancher-backups"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:GetObject",
            "s3:DeleteObject",
            "s3:PutObjectAcl"
          ],
          "Resource": [
             "arn:aws:s3:::rancher-backups/*"
          ]
        }
      ]
    }

    After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the credentialSecretName directive can be left empty in the Backup custom resource.

    Examples​

    For example Backup custom resources, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    + \ No newline at end of file diff --git a/reference-guides/backup-restore-configuration/examples.html b/reference-guides/backup-restore-configuration/examples.html index c5d2e8fed63..7472d41e513 100644 --- a/reference-guides/backup-restore-configuration/examples.html +++ b/reference-guides/backup-restore-configuration/examples.html @@ -5,13 +5,13 @@ Examples | Rancher Manager - +
    Version: v2.6

    Examples

    This section contains examples of Backup and Restore custom resources.

    The default backup storage location is configured when the rancher-backup operator is installed or upgraded.

    Encrypted backups can only be restored if the Restore custom resource uses the same encryption configuration secret that was used to create the backup.

    Backup​

    This section contains example Backup custom resources.

    Note: Refer to the backup config reference page for more information on configuring the options below.

    Backup in the Default Location with Encryption​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-location-encrypted-backup
    spec:
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Recurring Backup in the Default Location​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-location-recurring-backup
    spec:
      resourceSetName: rancher-resource-set
      schedule: "@every 1h"
      retentionCount: 10

    Encrypted Recurring Backup in the Default Location​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-enc-recurring-backup
    spec:
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig
      schedule: "@every 1h"
      retentionCount: 3

    Encrypted Backup in Minio​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: minio-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: minio-creds
          credentialSecretNamespace: default
          bucketName: rancherbackups
          endpoint: minio.xip.io
          endpointCA: <base64-encoded-cert>
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Backup in S3 Using AWS Credential Secret​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Recurring Backup in S3 Using AWS Credential Secret​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-recurring-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig
      schedule: "@every 1h"
      retentionCount: 10

    Backup from EC2 Nodes with IAM Permission to Access S3​

    This example shows that the AWS credential secret does not have to be provided to create a backup if the nodes running rancher-backup have these permissions for access to S3.

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-iam-backup
    spec:
      storageLocation:
        s3:
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Restore​

    This section contains example Restore custom resources.

    Note: Refer to the restore config reference page for more information on configuring the options below.

    Restore Using the Default Backup File Location​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-default
    spec:
      backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz
    #  encryptionConfigSecretName: test-encryptionconfig

    Restore for Rancher Migration​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-migration
    spec:
      backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
      prune: false
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com

    Restore from Encrypted Backup​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-encrypted
    spec:
      backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz
      encryptionConfigSecretName: encryptionconfig

    Restore an Encrypted Backup from Minio​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-minio
    spec:
      backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz
      storageLocation:
        s3:
          credentialSecretName: minio-creds
          credentialSecretNamespace: default
          bucketName: rancherbackups
          endpoint: minio.xip.io
          endpointCA: <base64-encoded-cert>
      encryptionConfigSecretName: test-encryptionconfig

    Restore from Backup Using an AWS Credential Secret to Access S3​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-s3-demo
    spec:
      backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      encryptionConfigSecretName: test-encryptionconfig

    Restore from EC2 Nodes with IAM Permissions to Access S3​

    This example shows that the AWS credential secret does not have to be provided to restore from backup if the nodes running rancher-backup have these permissions for access to S3.

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-s3-demo
    spec:
      backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz
      storageLocation:
        s3:
          bucketName: rajashree-backup-test
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      encryptionConfigSecretName: test-encryptionconfig

    Example Credential Secret for Storing Backups in S3

    apiVersion: v1
    kind: Secret
    metadata:
      name: creds
    type: Opaque
    data:
      accessKey: <Enter your base64-encoded access key>
      secretKey: <Enter your base64-encoded secret key>

    Example EncryptionConfiguration

    The snippet below demonstrates two different types of secrets and their relevance with respect to Backup and Restore of custom resources.

    The first example is that of a secret that is used to encrypt the backup files. The backup operator, in this case, will not be able to read the secrets encryption file. It only uses the contents of the secret.

    The second example is that of a Kubernetes secrets encryption config file that is used to encrypt secrets when stored in etcd. When backing up the etcd datastore, be sure to also back up the EncryptionConfiguration. Failure to do so will result in an inability to use the restored data if secrets encryption was in use at the time the data was backed up.

    apiVersion: apiserver.config.k8s.io/v1
    kind: EncryptionConfiguration
    resources:
      - resources:
          - secrets
        providers:
          - aesgcm:
              keys:
                - name: key1
                  secret: c2VjcmV0IGlzIHNlY3VyZQ==
                - name: key2
                  secret: dGhpcyBpcyBwYXNzd29yZA==
          - aescbc:
              keys:
                - name: key1
                  secret: c2VjcmV0IGlzIHNlY3VyZQ==
                - name: key2
                  secret: dGhpcyBpcyBwYXNzd29yZA==
          - secretbox:
              keys:
                - name: key1
                  secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/backup-restore-configuration/restore-configuration.html b/reference-guides/backup-restore-configuration/restore-configuration.html index 6c0c2cc87cc..573716bb112 100644 --- a/reference-guides/backup-restore-configuration/restore-configuration.html +++ b/reference-guides/backup-restore-configuration/restore-configuration.html @@ -5,13 +5,13 @@ Restore Configuration | Rancher Manager - +
    Version: v2.6

    Restore Configuration

    The Restore Create page lets you provide details of the backup to restore from

    Backup Source​

    Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details

    An existing backup config​

    Selecting this option will populate the Target Backup dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the Backup Filename field for you, and will also pass the backup source information from the selected Backup to the operator.

    If the Backup custom resource does not exist in the cluster, you need to get the exact filename and provide the backup source details with the default storage target or an S3-compatible object store.

    The default storage target​

    Select this option if you are restoring from a backup file that exists in the default storage location configured at the operator-level. The operator-level configuration is the storage location that was configured when the rancher-backup operator was installed or upgraded. Provide the exact filename in the Backup Filename field.

    An S3-compatible object store​

    Select this option if no default storage location is configured at the operator-level, OR if the backup file exists in a different S3 bucket than the one configured as the default storage location. Provide the exact filename in the Backup Filename field. Refer to this section for exact steps on getting the backup filename from s3. Fill in all the details for the S3 compatible object store. Its fields are exactly same as ones for the backup.StorageLocation configuration in the Backup custom resource.

    Encryption​

    If the backup was created with encryption enabled, its file will have .enc suffix. Choosing such a Backup, or providing a backup filename with .enc suffix will display another dropdown named Encryption Config Secret.

    The Secret selected from this dropdown must have the same contents as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail

    The Encryption Config Secret dropdown will filter out and list only those Secrets that have this exact key

    YAML Directive NameDescription
    encryptionConfigSecretNameProvide the name of the Secret from cattle-resources-system namespace, that contains the encryption config file.
    Important:

    This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail.

    Prune During Restore​

    • Prune: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the Prune flag is enabled. Prune is enabled by default and it is recommended to keep it enabled.
    • Delete Timeout: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.
    YAML Directive NameDescription
    pruneDelete the resources managed by Rancher that are not present in the backup (Recommended).
    deleteTimeoutSecondsAmount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.

    Getting the Backup Filename from S3​

    This is the name of the backup file that the rancher-backup operator will use to perform the restore.

    To obtain this file name from S3, go to your S3 bucket (and folder if it was specified while performing backup).

    Copy the filename and store it in your Restore custom resource. So assuming the name of your backup file is backupfile,

    • If your bucket name is s3bucket and no folder was specified, then the backupFilename to use will be backupfile.
    • If your bucket name is s3bucket and the base folder iss3folder, the backupFilename to use is only backupfile .
    • If there is a subfolder inside s3Folder called s3sub, and that has your backup file, then the backupFilename to use is s3sub/backupfile.
    YAML Directive NameDescription
    backupFilenameThis is the name of the backup file that the rancher-backup operator will use to perform the restore.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/backup-restore-configuration/storage-configuration.html b/reference-guides/backup-restore-configuration/storage-configuration.html index b4108837d69..4b50b6a0ffd 100644 --- a/reference-guides/backup-restore-configuration/storage-configuration.html +++ b/reference-guides/backup-restore-configuration/storage-configuration.html @@ -5,14 +5,14 @@ Backup Storage Location Configuration | Rancher Manager - +
    Version: v2.6

    Backup Storage Location Configuration

    Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible object store.

    Only one storage location can be configured at the operator level.

    Storage Location Configuration​

    No Default Storage Location​

    You can choose to not have any operator-level storage location configured. If you select this option, you must configure an S3-compatible object store as the storage location for each individual backup.

    S3-compatible Object Store​

    ParameterDescription
    Credential SecretChoose the credentials for S3 from your secrets in Rancher. Example.
    Bucket NameEnter the name of the S3 bucket where the backups will be stored. Default: rancherbackups.
    RegionThe AWS region where the S3 bucket is located.
    FolderThe folder in the S3 bucket where the backups will be stored.
    EndpointThe S3 endpoint For example, s3.us-west-2.amazonaws.com.
    Endpoint CAThe CA cert used to for the S3 endpoint. Default: base64 encoded CA cert
    insecureTLSSkipVerifySet to true if you are not using TLS.

    Existing StorageClass​

    Installing the rancher-backup chart by selecting the StorageClass option will create a Persistent Volume Claim (PVC), and Kubernetes will in turn dynamically provision a Persistent Volume (PV) where all the backups will be saved by default.

    For information about creating storage classes refer to this section.

    Important:

    It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the rancher-backup chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it.

    Existing Persistent Volume​

    Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to this section.

    Important:

    It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the rancher-backup chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.

    Example values.yaml for the rancher-backup Helm Chart​

    The documented values.yaml file that can be used to configure rancher-backup operator when the Helm CLI is used can be found in the backup-restore-operator repository.

    For more information about values.yaml files and configuring Helm charts during installation, refer to the Helm documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html b/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html index 2ad968ba348..562ab01e9f1 100644 --- a/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html +++ b/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html @@ -5,13 +5,13 @@ Logging Best Practices | Rancher Manager - +
    Version: v2.6

    Logging Best Practices

    In this guide, we recommend best practices for cluster-level logging and application logging.

    Before Rancher v2.5, logging in Rancher has historically been a pretty static integration. There were a fixed list of aggregators to choose from (ElasticSearch, Splunk, Kafka, Fluentd and Syslog), and only two configuration points to choose (Cluster-level and Project-level).

    Rancher provides a flexible experience for log aggregation. With the logging feature, administrators and users alike can deploy logging that meets fine-grained collection criteria while offering a wider array of destinations and configuration options.

    "Under the hood", Rancher logging uses the Banzai Cloud logging operator. We provide manageability of this operator (and its resources), and tie that experience in with managing your Rancher clusters.

    Cluster-level Logging​

    Cluster-wide Scraping​

    For some users, it is desirable to scrape logs from every container running in the cluster. This usually coincides with your security team's request (or requirement) to collect all logs from all points of execution.

    In this scenario, it is recommended to create at least two ClusterOutput objects - one for your security team (if you have that requirement), and one for yourselves, the cluster administrators. When creating these objects take care to choose an output endpoint that can handle the significant log traffic coming from the entire cluster. Also make sure to choose an appropriate index to receive all these logs.

    Once you have created these ClusterOutput objects, create a ClusterFlow to collect all the logs. Do not define any Include or Exclude rules on this flow. This will ensure that all logs from across the cluster are collected. If you have two ClusterOutputs, make sure to send logs to both of them.

    Kubernetes Components​

    ClusterFlows have the ability to collect logs from all containers on all hosts in the Kubernetes cluster. This works well in cases where those containers are part of a Kubernetes pod; however, RKE containers exist outside of the scope of Kubernetes.

    Currently the logs from RKE containers are collected, but are not able to easily be filtered. This is because those logs do not contain information as to the source container (e.g. etcd or kube-apiserver).

    A future release of Rancher will include the source container name which will enable filtering of these component logs. Once that change is made, you will be able to customize a ClusterFlow to retrieve only the Kubernetes component logs, and direct them to an appropriate output.

    Application Logging​

    Best practice not only in Kubernetes but in all container-based applications is to direct application logs to stdout/stderr. The container runtime will then trap these logs and do something with them - typically writing them to a file. Depending on the container runtime (and its configuration), these logs can end up in any number of locations.

    In the case of writing the logs to a file, Kubernetes helps by creating a /var/log/containers directory on each host. This directory symlinks the log files to their actual destination (which can differ based on configuration or container runtime).

    Rancher logging will read all log entries in /var/log/containers, ensuring that all log entries from all containers (assuming a default configuration) will have the opportunity to be collected and processed.

    Specific Log Files​

    Log collection only retrieves stdout/stderr logs from pods in Kubernetes. But what if we want to collect logs from other files that are generated by applications? Here, a log streaming sidecar (or two) may come in handy.

    The goal of setting up a streaming sidecar is to take log files that are written to disk, and have their contents streamed to stdout. This way, the Banzai Logging Operator can pick up those logs and send them to your desired output.

    To set this up, edit your workload resource (e.g. Deployment) and add the following sidecar definition:

    ...
    containers:
    - args:
      - -F
      - /path/to/your/log/file.log
      command:
      - tail
      image: busybox
      name: stream-log-file-[name]
      volumeMounts:
      - mountPath: /path/to/your/log
        name: mounted-log
    ...

    This will add a container to your workload definition that will now stream the contents of (in this example) /path/to/your/log/file.log to stdout.

    This log stream is then automatically collected according to any Flows or ClusterFlows you have setup. You may also wish to consider creating a Flow specifically for this log file by targeting the name of the container. See example:

    ...
    spec:
      match:
      - select:
          container_names:
          - stream-log-file-name
    ...

    General Best Practices​

    • Where possible, output structured log entries (e.g. syslog, JSON). This makes handling of the log entry easier as there are already parsers written for these formats.
    • Try to provide the name of the application that is creating the log entry, in the entry itself. This can make troubleshooting easier as Kubernetes objects do not always carry the name of the application as the object name. For instance, a pod ID may be something like myapp-098kjhsdf098sdf98 which does not provide much information about the application running inside the container.
    • Except in the case of collecting all logs cluster-wide, try to scope your Flow and ClusterFlow objects tightly. This makes it easier to troubleshoot when problems arise, and also helps ensure unrelated log entries do not show up in your aggregator. An example of tight scoping would be to constrain a Flow to a single Deployment in a namespace, or perhaps even a single container within a Pod.
    • Keep the log verbosity down except when troubleshooting. High log verbosity poses a number of issues, chief among them being noise: significant events can be drowned out in a sea of DEBUG messages. This is somewhat mitigated with automated alerting and scripting, but highly verbose logging still places an inordinate amount of stress on the logging infrastructure.
    • Where possible, try to provide a transaction or request ID with the log entry. This can make tracing application activity across multiple log sources easier, especially when dealing with distributed applications.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html b/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html index fabad718be1..6fa12e89bc1 100644 --- a/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html +++ b/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html @@ -5,13 +5,13 @@ Monitoring Best Practices | Rancher Manager - +
    Version: v2.6

    Monitoring Best Practices

    Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. This is not different when using Kubernetes and Rancher. Fortunately the integrated monitoring and alerting functionality makes this whole process a lot easier.

    The Rancher monitoring documentation describes how you can set up a complete Prometheus and Grafana stack. Out of the box this will scrape monitoring data from all system and Kubernetes components in your cluster and provide sensible dashboards and alerts for them to get started. But for a reliable setup, you also need to monitor your own workloads and adapt Prometheus and Grafana to your own specific use cases and cluster sizes. This document aims to give you best practices for this.

    What to Monitor​

    Kubernetes itself, as well as applications running inside of it, form a distributed system where different components interact with each other. For the whole system and each individual component, you have to ensure performance, availability, reliability and scalability. A good resource with more details and information is Google's free Site Reliability Engineering Book, especially the chapter about Monitoring distributed systems.

    Configuring Prometheus Resource Usage​

    When installing the integrated monitoring stack, Rancher allows to configure several settings that are dependent on the size of your cluster and the workloads running in it. This chapter covers these in more detail.

    Storage and Data Retention​

    The amount of storage needed for Prometheus directly correlates to the amount of time series and labels that you store and the data retention you have configured. It is important to note that Prometheus is not meant to be used as a long-term metrics storage. Data retention time is usually only a couple of days and not weeks or months. The reason for this is that Prometheus does not perform any aggregation on its stored metrics. This is great because aggregation can dilute data, but it also means that the needed storage grows linearly over time without retention.

    One way to calculate the necessary storage is to look at the average size of a storage chunk in Prometheus with this query

    rate(prometheus_tsdb_compaction_chunk_size_bytes_sum[1h]) / rate(prometheus_tsdb_compaction_chunk_samples_sum[1h])

    Next, find out your data ingestion rate per second:

    rate(prometheus_tsdb_head_samples_appended_total[1h])

    and then multiply this with the retention time, adding a few percentage points as buffer:

    average chunk size in bytes * ingestion rate per second * retention time in seconds * 1.1 = necessary storage in bytes

    You can find more information about how to calculate the necessary storage in this blog post.

    You can read more about the Prometheus storage concept in the Prometheus documentation.

    CPU and Memory Requests and Limits​

    In larger Kubernetes clusters Prometheus can consume quite a bit of memory. The amount of memory Prometheus needs directly correlates to the amount of time series and amount of labels it stores and the scrape interval in which these are filled.

    You can find more information about how to calculate the necessary memory in this blog post.

    The amount of necessary CPUs correlate with the amount of queries you are performing.

    Federation and Long-term Storage​

    Prometheus is not meant to store metrics for a long amount of time, but should only be used for short term storage.

    In order to store some, or all metrics for a long time, you can leverage Prometheus' remote read/write capabilities to connect it to storage systems like Thanos, InfluxDB, M3DB, or others. You can find an example setup in this blog post.

    Scraping Custom Workloads​

    While the integrated Rancher Monitoring already scrapes system metrics from a cluster's nodes and system components, the custom workloads that you deploy on Kubernetes should also be scraped for data. For that you can configure Prometheus to do an HTTP request to an endpoint of your applications in a certain interval. These endpoints should then return their metrics in a Prometheus format.

    In general, you want to scrape data from all the workloads running in your cluster so that you can use them for alerts or debugging issues. Often, you recognize that you need some data only when you actually need the metrics during an incident. It is good, if it is already scraped and stored. Since Prometheus is only meant to be a short-term metrics storage, scraping and keeping lots of data is usually not that expensive. If you are using a long-term storage solution with Prometheus, you can then still decide which data you are actually persisting and keeping there.

    About Prometheus Exporters​

    A lot of 3rd party workloads like databases, queues or web-servers either already support exposing metrics in a Prometheus format, or there are so called exporters available that translate between the tool's metrics and the format that Prometheus understands. Usually you can add these exporters as additional sidecar containers to the workload's Pods. A lot of helm charts already include options to deploy the correct exporter. Additionally you can find a curated list of exports by SysDig on promcat.io and on ExporterHub.

    Prometheus support in Programming Languages and Frameworks​

    To get your own custom application metrics into Prometheus, you have to collect and expose these metrics directly from your application's code. Fortunately, there are already libraries and integrations available to help with this for most popular programming languages and frameworks. One example for this is the Prometheus support in the Spring Framework.

    ServiceMonitors and PodMonitors​

    Once all your workloads expose metrics in a Prometheus format, you have to configure Prometheus to scrape it. Under the hood Rancher is using the prometheus-operator. This makes it easy to add additional scraping targets with ServiceMonitors and PodMonitors. A lot of helm charts already include an option to create these monitors directly. You can also find more information in the Rancher documentation.

    Prometheus Push Gateway​

    There are some workloads that are traditionally hard to scrape by Prometheus. Examples for these are short lived workloads like Jobs and CronJobs, or applications that do not allow sharing data between individual handled incoming requests, like PHP applications.

    To still get metrics for these use cases, you can set up prometheus-pushgateways. The CronJob or PHP application would push metric updates to the pushgateway. The pushgateway aggregates and exposes them through an HTTP endpoint, which then can be scraped by Prometheus.

    Prometheus Blackbox Monitor​

    Sometimes it is useful to monitor workloads from the outside. For this, you can use the Prometheus blackbox-exporter which allows probing any kind of endpoint over HTTP, HTTPS, DNS, TCP and ICMP.

    Monitoring in a (Micro)Service Architecture​

    If you have a (micro)service architecture where multiple individual workloads within your cluster are communicating with each other, it is really important to have detailed metrics and traces about this traffic to understand how all these workloads are communicating with each other and where a problem or bottleneck may be.

    Of course you can monitor all this internal traffic in all your workloads and expose these metrics to Prometheus. But this can quickly become quite work intensive. Service Meshes like Istio, which can be installed with a click in Rancher, can do this automatically and provide rich telemetry about the traffic between all services.

    Real User Monitoring​

    Monitoring the availability and performance of all your internal workloads is vitally important to run stable, reliable and fast applications. But these metrics only show you parts of the picture. To get a complete view it is also necessary to know how your end users are actually perceiving it. For this you can look into various Real user monitoring solutions.

    Security Monitoring​

    In addition to monitoring workloads to detect performance, availability or scalability problems, the cluster and the workloads running into it should also be monitored for potential security problems. A good starting point is to frequently run and alert on CIS Scans which check if the cluster is configured according to security best practices.

    For the workloads, you can have a look at Kubernetes and Container security solutions like NeuVector, Falco, Aqua Kubernetes Security, SysDig.

    Setting up Alerts​

    Getting all the metrics into a monitoring systems and visualizing them in dashboards is great, but you also want to be pro-actively alerted if something goes wrong.

    The integrated Rancher monitoring already configures a sensible set of alerts that make sense in any Kubernetes cluster. You should extend these to cover your specific workloads and use cases.

    When setting up alerts, configure them for all the workloads that are critical to the availability of your applications. But also make sure that they are not too noisy. Ideally every alert you are receiving should be because of a problem that needs your attention and needs to be fixed. If you have alerts that are firing all the time but are not that critical, there is a danger that you start ignoring your alerts all together and then miss the real important ones. Less may be more here. Start to focus on the real important metrics first, for example alert if your application is offline. Fix all the problems that start to pop up and then start to create more detailed alerts.

    If an alert starts firing, but there is nothing you can do about it at the moment, it's also fine to silence the alert for a certain amount of time, so that you can look at it later.

    You can find more information on how to set up alerts and notification channels in the Rancher Documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html b/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html index d8e7c456091..6f73af47089 100644 --- a/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html +++ b/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html @@ -5,13 +5,13 @@ Best Practices for Rancher Managed vSphere Clusters | Rancher Manager - +
    Version: v2.6

    Best Practices for Rancher Managed vSphere Clusters

    This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Solution Overview

    Solution Overview

    1. VM Considerations

    Leverage VM Templates to Construct the Environment​

    To facilitate consistency across the deployed Virtual Machines across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customisation options.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across ESXi Hosts​

    Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across Datastores​

    Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.

    Configure VM's as Appropriate for Kubernetes​

    It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.

    2. Network Considerations

    Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes​

    Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.

    Consistent IP Addressing for VM's​

    Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    3. Storage Considerations

    Leverage SSD Drives for ETCD Nodes​

    ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.

    4. Backups and Disaster Recovery

    Perform Regular Downstream Cluster Backups​

    Kubernetes uses etcd to store all its data - from configuration, state and metadata. Backing this up is crucial in the event of disaster recovery.

    Back up Downstream Node VMs​

    Incorporate the Rancher downstream node VM's within a standard VM backup policy.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html b/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html index a9b8afa336e..f629b541dfa 100644 --- a/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html +++ b/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html @@ -5,13 +5,13 @@ Tips for Setting Up Containers | Rancher Manager - +
    Version: v2.6

    Tips for Setting Up Containers

    Running well-built containers can greatly impact the overall performance and security of your environment.

    Below are a few tips for setting up your containers.

    For a more detailed discussion of security for containers, you can also refer to Rancher's Guide to Container Security.

    Use a Common Container OS​

    When possible, you should try to standardize on a common container base OS.

    Smaller distributions such as Alpine and BusyBox reduce container image size and generally have a smaller attack/vulnerability surface.

    Popular distributions such as Ubuntu, Fedora, and CentOS are more field-tested and offer more functionality.

    Start with a FROM scratch container​

    If your microservice is a standalone static binary, you should use a FROM scratch container.

    The FROM scratch container is an official Docker image that is empty so that you can use it to design minimal images.

    This will have the smallest attack surface and smallest image size.

    Run Container Processes as Unprivileged​

    When possible, use a non-privileged user when running processes within your container. While container runtimes provide isolation, vulnerabilities and attacks are still possible. Inadvertent or accidental host mounts can also be impacted if the container is running as root. For details on configuring a security context for a pod or container, refer to the Kubernetes docs.

    Define Resource Limits​

    Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices.

    In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs.

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    The Kubernetes docs have more information on how resource limits can be set at the container level and the namespace level.

    Define Resource Requirements​

    You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining resources.requests in the resource requests field in a pod's container spec. For details, refer to the Kubernetes docs.

    note

    If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load.

    Liveness and Readiness Probes​

    Set up liveness and readiness probes for your container. Unless your container completely crashes, Kubernetes will not know it's unhealthy unless you create an endpoint or mechanism that can report container status. Alternatively, make sure your container halts and crashes if unhealthy.

    The Kubernetes docs show how to configure liveness and readiness probes for containers.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html b/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html index 142a0f974aa..2992e9c3601 100644 --- a/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html +++ b/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html @@ -5,13 +5,13 @@ Installing Rancher in a vSphere Environment | Rancher Manager - +
    Version: v2.6

    Installing Rancher in a vSphere Environment

    This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Solution Overview

    Solution Overview

    1. Load Balancer Considerations​

    A load balancer is required to direct traffic to the Rancher workloads residing on the RKE nodes.

    Leverage Fault Tolerance and High Availability​

    Leverage the use of an external (hardware or software) load balancer that has inherit high-availability functionality (F5, NSX-T, Keepalived, etc).

    Back Up Load Balancer Configuration​

    In the event of a Disaster Recovery activity, availability of the Load balancer configuration will expedite the recovery process.

    Configure Health Checks​

    Configure the Load balancer to automatically mark nodes as unavailable if a health check is failed. For example, NGINX can facilitate this with:

    max_fails=3 fail_timeout=5s

    Leverage an External Load Balancer​

    Avoid implementing a software load balancer within the management cluster.

    Secure Access to Rancher​

    Configure appropriate Firewall / ACL rules to only expose access to Rancher

    2. VM Considerations​

    Size the VM's According to Rancher Documentation​

    https://rancher.com/docs/rancher/v2.6/en/installation/requirements/

    Leverage VM Templates to Construct the Environment​

    To facilitate the consistency of Virtual Machines deployed across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customization options.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across ESXi Hosts​

    Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across Datastores​

    Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.

    Configure VM's as Appropriate for Kubernetes​

    It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.

    3. Network Considerations​

    Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes​

    Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.

    Consistent IP Addressing for VM's​

    Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    4. Storage Considerations​

    Leverage SSD Drives for ETCD Nodes​

    ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.

    5. Backups and Disaster Recovery​

    Perform Regular Management Cluster Backups​

    Rancher stores its data in the ETCD datastore of the Kubernetes cluster it resides on. Like with any Kubernetes cluster, perform frequent, tested backups of this cluster.

    Back up Rancher Cluster Node VMs​

    Incorporate the Rancher management node VM's within a standard VM backup policy.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html b/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html index 2c781b49795..0b92534e4ff 100644 --- a/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html +++ b/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html @@ -5,13 +5,13 @@ Rancher Deployment Strategy | Rancher Manager - +
    Version: v2.6

    Rancher Deployment Strategy

    There are two recommended deployment strategies for a Rancher instance that manages downstream Kubernetes clusters. Each one has its own pros and cons. Read more about which one would fit best for your use case:

    Hub & Spoke Strategy​

    In this deployment scenario, there is a single Rancher instance managing Kubernetes clusters across the globe. The Rancher instance would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies.

    Pros​

    • Single control plane interface to view/see all regions and environments.
    • Kubernetes does not require Rancher to operate and can tolerate losing connectivity to the Rancher instance.

    Cons​

    • Subject to network latencies.
    • If Rancher goes down, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually.

    Regional Strategy​

    In the regional deployment model a Rancher instance is deployed in close proximity to the downstream Kubernetes clusters.

    Pros​

    • Rancher functionality in regions stay operational if a Rancher instance in another region goes down.
    • Network latency between Rancher and downstream clusters is greatly reduced, improving the performance of functionality in Rancher.
    • Upgrades of Rancher can be done independently per region.

    Cons​

    • Overhead of managing multiple Rancher installations.
    • Visibility into Kubernetes clusters in different regions requires multiple interfaces/panes of glass.
    • Deploying multi-cluster apps in Rancher requires repeating the process for each Rancher server.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html b/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html index 3f81d1e9547..5a0b33ada64 100644 --- a/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html +++ b/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html @@ -5,13 +5,13 @@ Tips for Running Rancher | Rancher Manager - +
    Version: v2.6

    Tips for Running Rancher

    This guide is geared toward use cases where Rancher is used to manage downstream Kubernetes clusters. The high-availability setup is intended to prevent losing access to downstream clusters if the Rancher server is not available.

    A high-availability Kubernetes installation, defined as an installation of Rancher on a Kubernetes cluster with at least three nodes, should be used in any production installation of Rancher, as well as any installation deemed "important." Multiple Rancher instances running on multiple nodes ensure high availability that cannot be accomplished with a single node environment.

    If you are installing Rancher in a vSphere environment, refer to the best practices documented here.

    When you set up your high-availability Rancher installation, consider the following:

    Run Rancher on a Separate Cluster​

    Don't run other workloads or microservices in the Kubernetes cluster that Rancher is installed on.

    Make sure nodes are configured correctly for Kubernetes​

    It's important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node, checking that all correct ports are opened, and deploying with ssd backed etcd. More details can be found in the kubernetes docs and etcd's performance op guide.

    When using RKE: Back up the Statefile​

    RKE keeps record of the cluster state in a file called cluster.rkestate. This file is important for the recovery of a cluster and/or the continued maintenance of the cluster through RKE. Because this file contains certificate material, we strongly recommend encrypting this file before backing up. After each run of rke up you should backup the state file.

    Run All Nodes in the Cluster in the Same Datacenter​

    For best performance, run all three of your nodes in the same geographic datacenter. If you are running nodes in the cloud, such as AWS, run each node in a separate Availability Zone. For example, launch node 1 in us-west-2a, node 2 in us-west-2b, and node 3 in us-west-2c.

    Development and Production Environments Should be Similar​

    It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration.

    Monitor Your Clusters to Plan Capacity​

    The Rancher server's Kubernetes cluster should run within the system and hardware requirements as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.

    However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types.

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus.

    After you enable monitoring in the cluster, you can set up alerts to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cli-with-rancher/kubectl-utility.html b/reference-guides/cli-with-rancher/kubectl-utility.html index 23fdd084c0d..9d7e5c605b6 100644 --- a/reference-guides/cli-with-rancher/kubectl-utility.html +++ b/reference-guides/cli-with-rancher/kubectl-utility.html @@ -5,14 +5,14 @@ kubectl Utility | Rancher Manager - +
    Version: v2.6

    kubectl

    Interact with Rancher using kubectl.

    kubectl Utility​

    Install the kubectl utility. See install kubectl.

    Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on Kubeconfig, copying contents, and putting them into your ~/.kube/config file.

    Run kubectl cluster-info or kubectl get pods successfully.

    Authentication with kubectl and kubeconfig Tokens with TTL​

    Requirements

    If admins have kubeconfig token generation turned off, the kubeconfig file requires the Rancher CLI to be present in your PATH when you run kubectl. Otherwise, you’ll see an error like: Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH.

    This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:

    1. Local
    2. Active Directory (LDAP only)
    3. FreeIPA
    4. OpenLDAP
    5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth

    When you first run kubectl, for example, kubectl get pods, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under ./.cache/token. This token is valid until it expires, or gets deleted from the Rancher server. Upon expiration, the next kubectl get pods will ask you to log in with the Rancher server again.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cli-with-rancher/rancher-cli.html b/reference-guides/cli-with-rancher/rancher-cli.html index bbd727df1bf..eb516efc51c 100644 --- a/reference-guides/cli-with-rancher/rancher-cli.html +++ b/reference-guides/cli-with-rancher/rancher-cli.html @@ -5,13 +5,13 @@ Rancher CLI | Rancher Manager - +
    Version: v2.6

    Rancher CLI

    The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.

    Download Rancher CLI​

    The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

    1. In the upper left corner, click ☰.
    2. At the bottom, click v2.6.x, where v2.6.x is a hyperlinked text indicating the installed Rancher version.
    3. Under the CLI Downloads section, there are links to download the binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

    Requirements​

    After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:

    • Your Rancher Server URL, which is used to connect to Rancher Server.
    • An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see Creating an API Key.

    CLI Authentication​

    Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace <BEARER_TOKEN> and <SERVER_URL> with your information):

    $ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>

    If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.

    Project Selection​

    Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a project to work on, use the command ./rancher context switch. When you enter this command, a list of available projects displays. Enter a number to choose your project.

    Example: ./rancher context switch Output

    User:rancher-cli-directory user$ ./rancher context switch
    NUMBER    CLUSTER NAME   PROJECT ID              PROJECT NAME
    1         cluster-2      c-7q96s:p-h4tmb         project-2
    2         cluster-2      c-7q96s:project-j6z6d   Default
    3         cluster-1      c-lchzv:p-xbpdt         project-1
    4         cluster-1      c-lchzv:project-s2mch   Default
    Select a Project:

    After you enter a number, the console displays a message that you've changed projects.

    INFO[0005] Setting new context to project project-1
    INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json

    Ensure you can run rancher kubectl get pods successfully.

    Commands​

    The following commands are available for use in Rancher CLI.

    CommandResult
    apps, [app]Performs operations on catalog applications (i.e., individual Helm charts) or Rancher charts.
    catalogPerforms operations on catalogs.
    clusters, [cluster]Performs operations on your clusters.
    contextSwitches between Rancher projects. For an example, see Project Selection.
    inspect [OPTIONS] [RESOURCEID RESOURCENAME]Displays details about Kubernetes resources or Rancher resources (i.e.: projects and workloads). Specify resources by name or ID.
    kubectlRuns kubectl commands.
    login, [l]Logs into a Rancher Server. For an example, see CLI Authentication.
    namespaces, [namespace]Performs operations on namespaces.
    nodes, [node]Performs operations on nodes.
    projects, [project]Performs operations on projects.
    psDisplays workloads in a project.
    settings, [setting]Shows the current settings for your Rancher Server.
    sshConnects to one of your cluster nodes using the SSH protocol.
    help, [h]Shows a list of commands or help for one command.

    Rancher CLI Help​

    Once logged into Rancher Server using the CLI, enter ./rancher --help for a list of commands.

    All commands accept the --help flag, which documents each command's usage.

    Limitations​

    The Rancher CLI cannot be used to install dashboard apps or Rancher feature charts.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.html index bfc7fe881f3..b99ba8a72cc 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/amazon-ec2.html @@ -5,13 +5,13 @@ EC2 Machine Configuration Reference | Rancher Manager - +
    Version: v2.6

    EC2 Machine Configuration Reference

    For more details about EC2 nodes, refer to the official documentation for the EC2 Management Console.

    Region​

    The geographical region in which to build your cluster.

    Zone​

    The zone, an isolated location within a region to build your cluster

    Instance Type​

    The instance type, which determines the hardware characteristics, used to provision your cluster.

    Root Disk Size​

    Configure the size (in GB) for your root device.

    VPC/Subnet​

    The VPC or specific subnet, an IP range in your VPC, to add your resources to.

    IAM Instance Profile Name​

    The name of the [instance profile] used to pass an IAM role to an EC2 instance.

    Advanced Options​

    AMI ID​

    The Amazon Machine Image used for the nodes in your cluster.

    SSH Username for AMI​

    The username for connecting to your launched instances. Refer to here for the default usernames to selected AMIs. For AMIs not listed, check with the AMI provider.

    Security Group​

    Choose the default security group or configure a security group.

    Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group.

    EBS Root Volume Type​

    The EBS volume type to use for the root device.

    Encrypt EBS Volume​

    Enable Amazon EBS Encryption.

    Request Spot Instance​

    Enable option to request spot instances and specify the maximum instance price per hour you're willing to pay.

    Use only private address​

    Enable option on use only private addresses.

    EBS-Optimized Instance​

    Use an EBS-optimized instance.

    Allow access to EC2 metadata​

    Enable access to EC2 metadata.

    Use tokens for metadata​

    Use Instance Metadata Service Version 2 (IMDSv2), a token-based method to access metadata.

    Add Tag​

    Add metadata using tags to categorize resources.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.html index d5841ac3e5b..156e34d64b2 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/azure.html @@ -5,13 +5,13 @@ Azure Machine Configuration | Rancher Manager - +
    Version: v2.6

    Azure Machine Configuration

    For more information about Azure, refer to the official Azure documentation.

    Environment​

    Microsoft provides multiple clouds for compliance with regional laws, which are available for your use:

    • AzurePublicCloud
    • AzureGermanCloud
    • AzureChinaCloud
    • AzureUSGovernmentCloud

    Location​

    Configure the cluster and node location.

    Resource Group​

    A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group.

    Use an existing resource group or enter a resource group name and one will be created for you.

    For information on managing resource groups, see the Azure documentation.

    Availability Set (unmanaged)​

    Name or ID of an existing availability set to add the VM to.

    Image​

    The name of the operating system image provided as an ARM resource identifier. Requires using managed disk.

    VM Size​

    Choose a size for each VM in the node pool. For details about each VM size, see this page.

    Advanced Options​

    Fault Domain Count​

    Fault domains define the group of virtual machines that share a common power source and network switch. If the availability set has already been created, the fault domain count will be ignored.

    For more information on fault domains, see refer here.

    Update Domain Count​

    Update domains indicate groups of virtual machines and underlying physical hardware that can be rebooted at the same time. If the availability set has already been created, the update domain count will be ignored.

    For more information on update domains, see refer here.

    Purchase Plan​

    Some VM images in the Azure Marketplace require a plan. If applicable, select a purchase plan, formatted as publisher:product:plan, to use with your chosen image.

    Subnet​

    The name of the subnet when creating a new VNet or referencing an existing one.

    Default: docker-machine

    Subnet Prefix​

    The subnet IP address prefix to use when creating a new VNet in CIDR format.

    Default: 192.168.0.0/16

    Virtual Network​

    The virtual network to use or create if one does not exist. Formatted as [resourcegroup:]name.

    Public IP Options​

    No Public IP​

    Do not allocate a public IP address.

    Static Public IP​

    Allocate a static public IP address.

    Use Private IP​

    Use a static private IP address.

    Private IP Address​

    Configure a static private IP address to use.

    Network Security Group​

    The network security group to use. All nodes using this template will use the supplied network security group. If no network security group is provided, a new one will be created for each node.

    DNS Label​

    A unique DNS name label for the public IP address.

    Storage Type​

    The storage account type to use with your VMs. Options include Standard LRS, Standard ZRS, Standard GRS, Standard RAGRS, and Premium LRS.

    Use Managed Disks​

    Azure managed disks are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability.

    Managed Disk Size​

    The size in GB for the disk for each node.

    SSH Username​

    The username used to create an SSH connection to your nodes.

    Open Port​

    Opens inbound traffic on specified ports. When using an existing Network Security Group, Open Ports are ignored.

    Default: 2379/tcp, 2380/tcp, 6443/tcp, 9796/tcp, 10250/tcp, 10251/tcp, 10252/tcp, 10256/tcp and 8472/udp, 4789/udp

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.html index c5030e93615..275d13c824b 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/machine-configuration/digitalocean.html @@ -5,13 +5,13 @@ DigitalOcean Machine Configuration | Rancher Manager - +
    Version: v2.6

    DigitalOcean Machine Configuration

    For more details about DigitalOcean, Droplets, refer to the official documentation.

    Region​

    Configure the region where Droplets are created.

    Size​

    Configure the size of Droplets.

    OS Image​

    Configure the operating system image Droplets are created from.

    Monitoring​

    Enable the DigitalOcean agent for additional monitoring.

    IPv6​

    Enable IPv6 for Droplets.

    Private Networking​

    Enable private networking for Droplets.

    Droplet Tags​

    Apply a tag (label) to a Droplet. Tags may only contain letters, numbers, colons, dashes, and underscores. For example, my_server.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html index ad4acfcdd62..adff1cccccf 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html @@ -5,13 +5,13 @@ EC2 Node Template Configuration | Rancher Manager - +
    Version: v2.6

    EC2 Node Template Configuration

    For more details about EC2, nodes, refer to the official documentation for the EC2 Management Console.

    Region​

    In the Region field, select the same region that you used when creating your cloud credentials.

    Cloud Credentials​

    Your AWS account access information, stored in a cloud credential.

    See Amazon Documentation: Creating Access Keys how to create an Access Key and Secret Key.

    See Amazon Documentation: Creating IAM Policies (Console) how to create an IAM policy.

    See Amazon Documentation: Adding Permissions to a User (Console) how to attach an IAM

    See our three example JSON policies:

    Authenticate & Configure Nodes​

    Choose an availability zone and network settings for your cluster.

    Security Group​

    Choose the default security group or configure a security group.

    Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group.

    New in v2.6.4

    If you provide your own security group for an EC2 instance, please note that Rancher will not modify it. As such, you will be responsible for ensuring that your security group is set to allow the necessary ports for Rancher to provision the instance. For more information on controlling inbound and outbound traffic to EC2 instances with security groups, refer here.

    Instance Options​

    Configure the instances that will be created. Make sure you configure the correct SSH User for the configured AMI. It is possible that a selected region does not support the default instance type. In this scenario you must select an instance type that does exist, otherwise an error will occur stating the requested configuration is not supported.

    If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a Kubernetes Cloud Provider, you will need an additional permission in your policy. See Example IAM policy with PassRole for an example policy.

    Engine Options​

    In the Engine Options section of the node template, you can configure the Docker daemon. You may want to specify the docker version or a Docker registry mirror.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html index 07ee4a71ce6..c7289cce19b 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html @@ -5,13 +5,13 @@ Azure Node Template Configuration | Rancher Manager - +
    Version: v2.6

    Azure Node Template Configuration

    For more information about Azure, refer to the official Azure documentation.

    Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

    • Placement sets the geographical region where your cluster is hosted and other location metadata.
    • Network configures the networking used in your cluster.
    • Instance customizes your VM configuration.

    The Docker daemon configuration options include:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html index 47cf4fc37ef..399564e9c6c 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html @@ -5,13 +5,13 @@ DigitalOcean Node Template Configuration | Rancher Manager - +
    Version: v2.6

    DigitalOcean Node Template Configuration

    Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

    Droplet Options​

    The Droplet Options provision your cluster's geographical region and specifications.

    Docker Daemon​

    The Docker daemon configuration options include:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.html index 7d973331cab..178e1c7eca4 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/nutanix.html @@ -5,13 +5,13 @@ Nutanix Node Template Configuration | Rancher Manager - +
    Version: v2.6

    Nutanix Node Template Configuration

    Account Access​

    ParameterRequiredDescriptionDefault
    Management Endpoint✓Hostname/IP address of Prism Central
    Username✓Username of the Prism Central user
    Password✓Password of the Prism Central user
    Allow insecure communicationSet to true to allow insecure SSL communication to Prism CentralFalse

    Scheduling​

    Choose what Nutanix cluster the virtual machine will be scheduled to.

    ParameterRequiredDescription
    Cluster✓Name of the Nutanix cluster where the VM should be deployed (case sensitive)

    Instance Options​

    In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

    ParameterRequiredDescriptionDefault
    CPUsNumber of vCPUs allocated to the VM (cores)2
    MemoryAmount of RAM allocated to the VM (MB)2 GB
    Template Image✓Name of the Disk Image template to clone as the VM's primary disk (must support cloud-init)
    VM Disk SizeNew size of the VM's primary disk (in GiB)
    Additional Disk SizeSize of an additional disk to add to the VM (in GiB)
    Storage ContainerStorage container UUID in which to provision an additional disk
    Cloud Config YAMLCloud-init to provide to the VM (will be patched with Rancher root user)
    Network✓Name(s) of the network(s) to attach to the VM
    VM CategoriesName(s) of any categories to be applied to the VM

    The VM may use any modern Linux operating system that is configured with support for cloud-init using the Config Drive v2 datasource.

    Networks​

    The node template allows a VM to be provisioned with multiple networks. In the Network field, you can click Add to add any networks available to you in AOS.

    VM Categories​

    A category is a grouping of entities into a key value pair. Typically, VMs are assigned to a category based on some criteria. Policies can then be tied to those entities that are assigned (grouped by) a specific category value.

    cloud-init​

    Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users or authorizing SSH keys.

    To make use of cloud-init initialization, paste a cloud config using valid YAML syntax into the Cloud Config YAML field. Refer to the cloud-init documentation for a commented set of examples of supported cloud config directives.

    Note that cloud-init based network configuration is not recommended and only supported via user data runcmd rather than by NoCloud or other network configuration datasources.

    Nutanix IP Address Management (IPAM) or another DHCP service is recommended.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html index 9c8b9245971..c3b45260d2c 100644 --- a/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html +++ b/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html @@ -5,13 +5,13 @@ VSphere Node Template Configuration | Rancher Manager - +
    Version: v2.6

    VSphere Node Template Configuration

    Account Access​

    ParameterRequiredDescription
    Cloud Credentials*Your vSphere account access information, stored in a cloud credential.

    Your cloud credential has these fields:

    Credential FieldDescription
    vCenter or ESXi ServerEnter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
    PortOptional: configure configure the port of the vCenter or ESXi server.
    Username and passwordEnter your vSphere login username and password.

    Scheduling​

    Choose what hypervisor the virtual machine will be scheduled to.

    The fields in the Scheduling section should auto-populate with the data center and other scheduling options that are available to you in vSphere.

    FieldRequiredExplanation
    Data Center*Choose the name/path of the data center where the VM will be scheduled.
    Resource PoolName of the resource pool to schedule the VMs in. Resource pools can be used to partition available CPU and memory resources of a standalone host or cluster, and they can also be nested. Leave blank for standalone ESXi. If not specified, the default resource pool is used.
    Data Store*If you have a data store cluster, you can toggle the Data Store field. This lets you select a data store cluster where your VM will be scheduled to. If the field is not toggled, you can select an individual disk.
    FolderName of a folder in the datacenter to create the VMs in. Must already exist. The VM folders in this dropdown menu directly correspond to your VM folders in vSphere. The folder name should be prefaced with vm/ in your vSphere config file.
    HostThe IP of the host system to schedule VMs in. Leave this field blank for a standalone ESXi or for a cluster with DRS (Distributed Resource Scheduler). If specified, the host system's pool will be used and the Resource Pool parameter will be ignored.

    Instance Options​

    In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

    ParameterRequiredDescription
    CPUs*Number of vCPUS to assign to VMs.
    Memory*Amount of memory to assign to VMs.
    Disk*Size of the disk (in MB) to attach to the VMs.
    Creation method*The method for setting up an operating system on the node. The operating system can be installed from an ISO or from a VM template. Depending on the creation method, you will also have to specify a VM template, content library, existing VM, or ISO. For more information on creation methods, refer to About VM Creation Methods.
    Cloud InitURL of a cloud-config.yml file or URL to provision VMs with. This file allows further customization of the operating system, such as network configuration, DNS servers, or system daemons. The operating system must support cloud-init.
    NetworksName(s) of the network to attach the VM to.
    Configuration Parameters used for guestinfoAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

    About VM Creation Methods​

    In the Creation method field, configure the method used to provision VMs in vSphere. Available options include creating VMs that boot from a RancherOS ISO or creating VMs by cloning from an existing virtual machine or VM template.

    The existing VM or template may use any modern Linux operating system that is configured with support for cloud-init using the NoCloud datasource.

    Choose the way that the VM will be created:

    • Deploy from template: Data Center: Choose a VM template that exists in the data center that you selected.
    • Deploy from template: Content Library: First, select the Content Library that contains your template, then select the template from the populated list Library templates.
    • Clone an existing virtual machine: In the Virtual machine field, choose an existing VM that the new VM will be cloned from.
    • Install from boot2docker ISO: Ensure that the OS ISO URL field contains the URL of a VMware ISO release for RancherOS (rancheros-vmware.iso). Note that this URL must be accessible from the nodes running your Rancher server installation.

    Networks​

    The node template now allows a VM to be provisioned with multiple networks. In the Networks field, you can now click Add Network to add any networks available to you in vSphere.

    Node Tags and Custom Attributes​

    Tags allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

    For tags, all your vSphere tags will show up as options to select from in your node template.

    In the custom attributes, Rancher will let you select all the custom attributes you have already set up in vSphere. The custom attributes are keys and you can enter values for each one.

    note

    Custom attributes are a legacy feature that will eventually be removed from vSphere.

    cloud-init​

    Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

    To make use of cloud-init initialization, create a cloud config file using valid YAML syntax and paste the file content in the the Cloud Init field. Refer to the cloud-init documentation. for a commented set of examples of supported cloud config directives.

    Note that cloud-init is not supported when using the ISO creation method.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.html b/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.html index 90c632d1e07..91ff2fc5e84 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/aks-cluster-configuration.html @@ -5,13 +5,13 @@ AKS Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    AKS Cluster Configuration Reference

    Changes in Rancher v2.6​

    • Support for adding more than one node pool
    • Support for private clusters
    • Enabled autoscaling node pools
    • The AKS permissions are now configured in cloud credentials

    Role-based Access Control​

    When provisioning an AKS cluster in the Rancher UI, RBAC cannot be disabled. If role-based access control is disabled for the cluster in AKS, the cluster cannot be registered or imported into Rancher.

    Rancher can configure member roles for AKS clusters in the same way as any other cluster. For more information, see the section on role-based access control.

    Cloud Credentials​

    note

    The configuration information in this section assumes you have already set up a service principal for Rancher. For step-by-step instructions for how to set up the service principal, see this section.

    Subscription ID​

    To get the subscription ID, click All Services in the left navigation bar. Then click Subscriptions. Go to the name of the subscription that you want to associate with your Kubernetes cluster and copy the Subscription ID.

    Client ID​

    To get the client ID, go to the Azure Portal, then click Azure Active Directory, then click App registrations, then click the name of the service principal. The client ID is listed on the app registration detail page as Application (client) ID.

    Client Secret​

    You can't retrieve the client secret value after it is created, so if you don't already have a client secret value, you will need to create a new client secret.

    To get a new client secret, go to the Azure Portal, then click Azure Active Directory, then click App registrations, then click the name of the service principal.

    Then click Certificates & secrets and click New client secret. Click Add. Then copy the Value of the new client secret.

    Environment​

    Microsoft provides multiple clouds for compliance with regional laws, which are available for your use:

    • AzurePublicCloud
    • AzureGermanCloud
    • AzureChinaCloud
    • AzureUSGovernmentCloud

    Account Access​

    In this section you will need to select an existing Azure cloud credential or create a new one.

    For help configuring your Azure cloud credential, see this section.

    Cluster Location​

    Configure the cluster and node location. For more information on availability zones for AKS, see the AKS documentation.

    The high availability locations include multiple availability zones.

    Cluster Options​

    Kubernetes Version​

    The available Kubernetes versions are dynamically fetched from the Azure API.

    Cluster Resource Group​

    A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group.

    Use an existing resource group or enter a resource group name and one will be created for you.

    Using a resource group containing an existing AKS cluster will create a new resource group. Azure AKS only allows one AKS cluster per resource group.

    For information on managing resource groups, see the Azure documentation.

    Linux Admin Username​

    The username used to create an SSH connection to the Linux nodes.

    The default username for AKS nodes is azureuser.

    SSH Public Key​

    The key used to create an SSH connection to the Linux nodes.

    Tags​

    Cluster tags can be useful if your organization uses tags as a way to organize resources across multiple Azure services. These tags don't apply to resources within the cluster.

    Networking Options​

    LoadBalancer SKU​

    Azure load balancers support both standard and basic SKUs (stock keeping units).

    For a comparison of standard and basic load balancers, see the official Azure documentation. Microsoft recommends the Standard load balancer.

    The Standard load balancer is required if you have selected one or more availability zones, or if you have more than one node pool.

    Network Policy​

    All pods in an AKS cluster can send and receive traffic without limitations, by default. To improve security, you can define rules that control the flow of traffic. The Network Policy feature in Kubernetes lets you define rules for ingress and egress traffic between pods in a cluster.

    Azure provides two ways to implement network policy. You choose a network policy option when you create an AKS cluster. The policy option can't be changed after the cluster is created:

    • Azure's own implementation, called Azure Network Policies. The Azure network policy requires the Azure CNI.
    • Calico Network Policies, an open-source network and network security solution founded by Tigera.

    You can also choose to have no network policy.

    For more information about the differences between Azure and Calico network policies and their capabilities, see the AKS documentation.

    DNS Prefix​

    Enter a unique DNS prefix for your cluster's Kubernetes API server FQDN.

    Network Plugin​

    There are two network plugins: kubenet and Azure CNI.

    The kubenet Kubernetes plugin is the default configuration for AKS cluster creation. When kubenet is used, each node in the cluster receives a routable IP address. The pods use NAT to communicate with other resources outside the AKS cluster. This approach reduces the number of IP addresses you need to reserve in your network space for pods to use.

    With the Azure CNI (advanced) networking plugin, pods get full virtual network connectivity and can be directly reached via their private IP address from connected networks. This plugin requires more IP address space.

    For more information on the differences between kubenet and Azure CNI, see the AKS documentation.

    HTTP Application Routing​

    When enabled, the HTTP application routing add-on makes it easier to access applications deployed to the AKS cluster. It deploys two components: a Kubernetes Ingress controller and an External-DNS controller.

    For more information, see the AKS documentation.

    Set Authorized IP Ranges​

    You can secure access to the Kubernetes API server using authorized IP address ranges.

    The Kubernetes API server exposes the Kubernetes API. This component provides the interaction for management tools, such as kubectl. AKS provides a single-tenant cluster control plane with a dedicated API server. By default, the API server is assigned a public IP address, and you should control access to it using Kubernetes-based or Azure-based RBAC.

    To secure access to the otherwise publicly accessible AKS control plane and API server, you can enable and use authorized IP ranges. These authorized IP ranges only allow defined IP address ranges to communicate with the API server.

    However, even if you use authorized IP address ranges, you should still use Kubernetes RBAC or Azure RBAC to authorize users and the actions they request.

    Container Monitoring​

    Container monitoring gives you performance visibility by collecting memory and processor metrics from controllers, nodes, and containers that are available in Kubernetes through the Metrics API. Container logs are also collected. After you enable monitoring, metrics and logs are automatically collected for you through a containerized version of the Log Analytics agent for Linux. Metrics are written to the metrics store and log data is written to the logs store associated with your Log Analytics workspace.

    Log Analytics Workspace Resource Group​

    The resource group containing the Log Analytics Workspace. You must create at least one workspace to use Azure Monitor Logs.

    Log Analytics Workspace Name​

    Data collected by Azure Monitor Logs is stored in one or more Log Analytics workspaces. The workspace defines the geographic location of the data, access rights defining which users can access data, and configuration settings such as the pricing tier and data retention.

    You must create at least one workspace to use Azure Monitor Logs. A single workspace may be suffxicient for all of your monitoring data, or may choose to create multiple workspaces depending on your requirements. For example, you might have one workspace for your production data and another for testing.

    For more information about Azure Monitor Logs, see the Azure documentation.

    Support Private Kubernetes Service​

    Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint.

    Rancher can connect to a private AKS cluster in one of two ways.

    The first way to ensure that Rancher is running on the same NAT as the AKS nodes.

    The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled.

    note

    Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the Cluster To register dropdown list. This outcome will be based on region.

    For more information about connecting to an AKS private cluster, see the AKS documentation.

    Node Pools​

    Mode​

    The Azure interface allows users to specify whether a Primary Node Pool relies on either system (normally used for control planes) or user (what is most typically needed for Rancher).

    For Primary Node Pools, you can specify Mode, OS, Count and Size.

    System node pools always require running nodes, so they cannot be scaled below one node. At least one system node pool is required.

    For subsequent node pools, the Rancher UI forces the default of User. User node pools allow you to scale to zero nodes. User node pools don't run any part of the Kubernetes controlplane.

    AKS doesn't expose the nodes that run the Kubernetes controlplane components.

    Availability Zones​

    Availability zones are unique physical locations within a region. Each zone is made up of one or more data centers equipped with independent power, cooling, and networking.

    Not all regions have support for availability zones. For a list of Azure regions with availability zones, see the Azure documentation.

    VM Size​

    Choose a size for each VM in the node pool. For details about each VM size, see this page.

    OS Disk Type​

    The nodes in the node pool can have either managed or ephemeral disks.

    Ephemeral OS disks are created on the local virtual machine storage and not saved to the remote Azure Storage. Ephemeral OS disks work well for stateless workloads, where applications are tolerant of individual VM failures, but are more affected by VM deployment time or reimaging the individual VM instances. With Ephemeral OS disk, you get lower read/write latency to the OS disk and faster VM reimage.

    Azure managed disks are block-level storage volumes that are managed by Azure and used with Azure Virtual Machines. Managed disks are designed for 99.999% availability. Managed disks achieve this by providing you with three replicas of your data, allowing for high durability.

    OS Disk Size​

    The size in GB for the disk for each node.

    Node Count​

    The number of nodes in the node pool. The maximum number of nodes may be limited by your Azure subscription.

    Max Pods Per Node​

    The maximum number of pods per node defaults to 110 with a maximum of 250.

    Enable Auto Scaling​

    When auto scaling is enabled, you will need to enter a minimum and maximum node count.

    When Auto Scaling is enabled, you can't manually scale the node pool. The scale is controlled by the AKS autoscaler.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html b/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html index be4cd38a0d7..12995bae847 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html @@ -5,13 +5,13 @@ EKS Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    EKS Cluster Configuration Reference

    Account Access​

    Complete each drop-down and field using the information obtained for your IAM policy.

    SettingDescription
    RegionFrom the drop-down choose the geographical region in which to build your cluster.
    Cloud CredentialsSelect the cloud credentials that you created for your IAM policy. For more information on creating cloud credentials in Rancher, refer to this page.

    Service Role​

    Choose a service role.

    Service RoleDescription
    Standard: Rancher generated service roleIf you choose this role, Rancher automatically adds a service role for use with the cluster.
    Custom: Choose from your existing service rolesIf you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the Amazon documentation.

    Secrets Encryption​

    Optional: To encrypt secrets, select or enter a key created in AWS Key Management Service (KMS)

    API Server Endpoint Access​

    Configuring Public/Private API access is an advanced use case. For details, refer to the EKS cluster endpoint access control documentation.

    Private-only API Endpoints​

    If you enable private and disable public API endpoint access when creating a cluster, then there is an extra step you must take in order for Rancher to connect to the cluster successfully. In this case, a pop-up will be displayed with a command that you will run on the cluster to register it with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster's Kubernetes API.

    There are two ways to avoid this extra manual step:

    • You can create the cluster with both private and public API endpoint access on cluster creation. You can disable public access after the cluster is created and in an active state and Rancher will continue to communicate with the EKS cluster.
    • You can ensure that Rancher shares a subnet with the EKS cluster. Then security groups can be used to enable Rancher to communicate with the cluster's API endpoint. In this case, the command to register the cluster is not needed, and Rancher will be able to communicate with your cluster. For more information on configuring security groups, refer to the security groups documentation.

    Public Access Endpoints​

    Optionally limit access to the public endpoint via explicit CIDR blocks.

    If you limit access to specific CIDR blocks, then it is recommended that you also enable the private access to avoid losing network communication to the cluster.

    One of the following is required to enable private access:

    • Rancher's IP must be part of an allowed CIDR block
    • Private access should be enabled, and Rancher must share a subnet with the cluster and have network access to the cluster, which can be configured with a security group

    For more information about public and private access to the cluster endpoint, refer to the Amazon EKS documentation.

    Subnet​

    OptionDescription
    Standard: Rancher generated VPC and SubnetWhile provisioning your cluster, Rancher generates a new VPC with 3 public subnets.
    Custom: Choose from your existing VPC and SubnetsWhile provisioning your cluster, Rancher configures your Control Plane and nodes to use a VPC and Subnet that you've already created in AWS.

    For more information, refer to the AWS documentation for Cluster VPC Considerations. Follow one of the sets of instructions below based on your selection from the previous step.

    Security Group​

    Amazon Documentation:

    Logging​

    Configure control plane logs to send to Amazon CloudWatch. You are charged the standard CloudWatch Logs data ingestion and storage costs for any logs sent to CloudWatch Logs from your clusters.

    Each log type corresponds to a component of the Kubernetes control plane. To learn more about these components, see Kubernetes Components in the Kubernetes documentation.

    For more information on EKS control plane logging, refer to the official documentation.

    Managed Node Groups​

    Amazon EKS managed node groups automate the provisioning and lifecycle management of nodes (Amazon EC2 instances) for Amazon EKS Kubernetes clusters.

    For more information about how node groups work and how they are configured, refer to the EKS documentation.

    Bring your own launch template​

    A launch template ID and version can be provided in order to easily configure the EC2 instances in a node group. If a launch template is provided, then none of the settings below will be configurable in Rancher. Therefore, using a launch template would require that all the necessary and desired settings from the list below would need to be specified in the launch template. Also note that if a launch template ID and version is provided, then only the template version can be updated. Using a new template ID would require creating a new managed node group.

    OptionDescriptionRequired/Optional
    Instance TypeChoose the hardware specs for the instance you're provisioning.Required
    Image IDSpecify a custom AMI for the nodes. Custom AMIs used with EKS must be configured properlyOptional
    Node Volume SizeThe launch template must specify an EBS volume with the desired sizeRequired
    SSH KeyA key to be added to the instances to provide SSH access to the nodesOptional
    User DataCloud init script in MIME multi-part formatOptional
    Instance Resource TagsTag each EC2 instance in the node groupOptional

    Rancher-managed launch templates​

    If you do not specify a launch template, then you will be able to configure the above options in the Rancher UI and all of them can be updated after creation. In order to take advantage of all of these options, Rancher will create and manage a launch template for you. Each cluster in Rancher will have one Rancher-managed launch template and each managed node group that does not have a specified launch template will have one version of the managed launch template. The name of this launch template will have the prefix "rancher-managed-lt-" followed by the display name of the cluster. In addition, the Rancher-managed launch template will be tagged with the key "rancher-managed-template" and value "do-not-modify-or-delete" to help identify it as Rancher-managed. It is important that this launch template and its versions not be modified, deleted, or used with any other clusters or managed node groups. Doing so could result in your node groups being "degraded" and needing to be destroyed and recreated.

    Custom AMIs​

    If you specify a custom AMI, whether in a launch template or in Rancher, then the image must be configured properly and you must provide user data to bootstrap the node. This is considered an advanced use case and understanding the requirements is imperative.

    If you specify a launch template that does not contain a custom AMI, then Amazon will use the EKS-optimized AMI for the Kubernetes version and selected region. You can also select a GPU enabled instance for workloads that would benefit from it.

    note

    The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template.

    Spot instances​

    Spot instances are now supported by EKS. If a launch template is specified, Amazon recommends that the template not provide an instance type. Instead, Amazon recommends providing multiple instance types. If the "Request Spot Instances" checkbox is enabled for a node group, then you will have the opportunity to provide multiple instance types.

    note

    Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration.

    Node Group Settings​

    The following settings are also configurable. All of these except for the "Node Group Name" are editable after the node group is created.

    OptionDescription
    Node Group NameThe name of the node group.
    Desired ASG SizeThe desired number of instances.
    Maximum ASG SizeThe maximum number of instances. This setting won't take effect until the Cluster Autoscaler is installed.
    Minimum ASG SizeThe minimum number of instances. This setting won't take effect until the Cluster Autoscaler is installed.
    LabelsKubernetes labels applied to the nodes in the managed node group.
    TagsThese are tags for the managed node group and do not propagate to any of the associated resources.

    Configuring the Refresh Interval​

    The eks-refresh-cron setting is deprecated. It has been migrated to the eks-refresh setting, which is an integer representing seconds.

    The default value is 300 seconds.

    The syncing interval can be changed by running kubectl edit setting eks-refresh.

    If the eks-refresh-cron setting was previously set, the migration will happen automatically.

    The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html b/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html index d92e2a88221..1f71deea2de 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html @@ -5,14 +5,14 @@ Private Clusters | Rancher Manager - +
    Version: v2.6

    Private Clusters

    In GKE, private clusters are clusters whose nodes are isolated from inbound and outbound traffic by assigning them internal IP addresses only. Private clusters in GKE have the option of exposing the control plane endpoint as a publicly accessible address or as a private address. This is different from other Kubernetes providers, which may refer to clusters with private control plane endpoints as "private clusters" but still allow traffic to and from nodes. You may want to create a cluster with private nodes, with or without a public control plane endpoint, depending on your organization's networking and security requirements. A GKE cluster provisioned from Rancher can use isolated nodes by selecting "Private Cluster" in the Cluster Options (under "Show advanced options"). The control plane endpoint can optionally be made private by selecting "Enable Private Endpoint".

    Private Nodes​

    Because the nodes in a private cluster only have internal IP addresses, they will not be able to install the cluster agent and Rancher will not be able to fully manage the cluster. This can be overcome in a few ways.

    Cloud NAT​

    caution

    Cloud NAT will incur charges.

    If restricting outgoing internet access is not a concern for your organization, use Google's Cloud NAT service to allow nodes in the private network to access the internet, enabling them to download the required images from Dockerhub and contact the Rancher management server. This is the simplest solution.

    Private registry​

    caution

    This scenario is not officially supported, but is described for cases in which using the Cloud NAT service is not sufficient.

    If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image registry on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need direct access to it.

    Private Control Plane Endpoint​

    If the cluster has a public endpoint exposed, Rancher will be able to reach the cluster, and no additional steps need to be taken. However, if the cluster has no public endpoint, then considerations must be made to ensure Rancher can access the cluster.

    Cloud NAT​

    caution

    Cloud NAT will incur charges.

    As above, if restricting outgoing internet access to the nodes is not a concern, then Google's Cloud NAT service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the kubeconfig for the new cluster and run the provided kubectl command on the cluster. Gaining access to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes.

    Direct access​

    If the Rancher server is run on the same VPC as the cluster's control plane, it will have direct access to the control plane's private endpoint. The cluster nodes will need to have access to a private registry to download images as described above.

    You can also use services from Google such as Cloud VPN or Cloud Interconnect VLAN to facilitate connectivity between your organization's network and your Google VPC.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.html b/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.html index c100c11dc55..d79baceae3e 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.html @@ -5,13 +5,13 @@ K3s Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    K3s Cluster Configuration Reference

    This section covers the configuration options that are available in Rancher for a new or existing K3s Kubernetes cluster.

    Overview​

    You can configure the Kubernetes options one of two ways:

    • Rancher UI: Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
    • Cluster Config File: Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create a K3s config file. Using a config file allows you to set any of the options available in an K3s installation.

    Configuration Options in the Rancher UI​

    tip

    Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the K3s cluster configuration file in YAML. For the complete reference of configurable options for K3s clusters in YAML, see the K3s documentation.

    Basics​

    Kubernetes Version​

    The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on hyperkube.

    For more detail, see Upgrading Kubernetes.

    Encrypt Secrets​

    Option to enable or disable secrets encryption. When enabled, secrets will be encrypted using a AES-CBC key. If disabled, any previously secrets will not be readable until encryption is enabled again. Refer to the K3s documentation for details.

    Project Network Isolation​

    If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.

    SELinux​

    Option to enable or disable SELinux support.

    CoreDNS​

    By default, CoreDNS is installed as the default DNS provider. If CoreDNS is not installed, an alternate DNS provider must be installed yourself. Refer to the K3s documentation for details..

    Klipper Service LB​

    Option to enable or disable the Klipper service load balancer. Refer to the K3s documentation for details.

    Traefik Ingress​

    Option to enable or disable the Traefik HTTP reverse proxy and load balancer. For more details and configuration options, see the K3s documentation.

    Local Storage​

    Option to enable or disable local storage on the node(s).

    Metrics Server​

    Option to enable or disable the metrics server. If enabled, ensure port 10250 is opened for inbound TCP traffic.

    Add-On Config​

    Additional Kubernetes manifests, managed as a Add-on, to apply to the cluster on startup. Refer to the K3s documentation for details.

    Agent Environment Vars​

    Option to set environment variables for K3s agents. The environment variables can be set using key value pairs. Refer to the K3 documentation for more details.

    etcd​

    Automatic Snapshots​

    Option to enable or disable recurring etcd snapshots. If enabled, users have the option to configure the frequency of snapshots. For details, refer to the K3s documentation.

    Metrics​

    Option to choose whether to expose etcd metrics to the public or only within the cluster.

    Networking​

    Cluster CIDR​

    IPv4/IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16).

    Service CIDR​

    IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16).

    Cluster DNS​

    IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10).

    Cluster Domain​

    Select the domain for the cluster. The default is cluster.local.

    NodePort Service Port Range​

    Option to change the range of ports that can be used for NodePort services. The default is 30000-32767.

    TLS Alternate Names​

    Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert.

    Authorized Cluster Endpoint​

    Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.

    For more detail on how an authorized cluster endpoint works and why it is used, refer to the architecture section.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Registries​

    Select the image repository to pull Rancher images from. For more details and configuration options, see the K3s documentation.

    Upgrade Strategy​

    Controle Plane Concurrency​

    Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.

    Worker Concurrency​

    Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.

    Drain Nodes (Control Plane)​

    Option to remove all pods from the node prior to upgrading.

    Drain Nodes (Worker Nodes)​

    Option to remove all pods from the node prior to upgrading.

    Advanced​

    Option to set kubelet options for different nodes. For available options, refer to the Kubernetes documentation.

    Cluster Config File​

    Instead of using the Rancher UI forms to choose Kubernetes options for the cluster, advanced users can create an K3s config file. Using a config file allows you to set any of the options available in an K3s installation.

    To edit an K3s config file directly from the Rancher UI, click Edit as YAML.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html b/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html index 90f0fb37cf6..659c8319a70 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html @@ -5,13 +5,13 @@ RKE Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    RKE Cluster Configuration Reference

    When Rancher installs Kubernetes, it uses RKE or RKE2 as the Kubernetes distribution.

    This section covers the configuration options that are available in Rancher for a new or existing RKE Kubernetes cluster.

    Overview​

    You can configure the Kubernetes options one of two ways:

    • Rancher UI: Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
    • Cluster Config File: Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

    The RKE cluster config options are nested under the rancher_kubernetes_engine_config directive. For more information, see the section about the cluster config file.

    In clusters launched by RKE, you can edit any of the remaining options that follow.

    For an example of RKE config file syntax, see the RKE documentation.

    The forms in the Rancher UI don't include all advanced options for configuring RKE. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    Editing Clusters with a Form in the Rancher UI​

    To edit your cluster,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster you want to configure and click ⋮ > Edit Config.

    Editing Clusters with YAML​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

    RKE clusters (also called RKE1 clusters) are edited differently than RKE2 and K3s clusters.

    To edit an RKE config file directly from the Rancher UI,

    1. Click ☰ > Cluster Management.
    2. Go to the RKE cluster you want to configure. Click and click ⋮ > Edit Config. This take you to the RKE configuration form. Note: Because cluster provisioning changed in Rancher 2.6, the ⋮ > Edit as YAML can be used for configuring RKE2 clusters, but it can't be used for editing RKE1 configuration.
    3. In the configuration form, scroll down and click Edit as YAML.
    4. Edit the RKE options under the rancher_kubernetes_engine_config directive.

    Configuration Options in the Rancher UI​

    tip

    Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE cluster configuration file in YAML. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    Kubernetes Version​

    The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on hyperkube.

    For more detail, see Upgrading Kubernetes.

    Network Provider​

    The Network Provider that the cluster uses. For more details on the different networking providers, please view our Networking FAQ.

    caution

    After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications.

    Out of the box, Rancher is compatible with the following network providers:

    Notes on Weave:

    When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a Config File and the Weave Network Plug-in Options.

    Project Network Isolation​

    If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.

    Project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.

    Kubernetes Cloud Providers​

    You can configure a Kubernetes cloud provider. If you want to use dynamically provisioned volumes and storage in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the aws cloud provider.

    note

    If the cloud provider you want to use is not listed as an option, you will need to use the config file option to configure the cloud provider. Please reference the RKE cloud provider documentation on how to configure the cloud provider.

    Private Registries​

    The cluster-level private registry configuration is only used for provisioning clusters.

    There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

    If your private registry requires credentials, you need to pass the credentials to Rancher by editing the cluster options for each cluster that needs to pull images from the registry.

    The private registry configuration option tells Rancher where to pull the system images or addon images that will be used in your cluster.

    • System images are components needed to maintain the Kubernetes cluster.
    • Add-ons are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server.

    For more information on setting up a private registry for components applied during the provisioning of the cluster, see the RKE documentation on private registries.

    Rancher v2.6 introduced the ability to configure ECR registries for RKE clusters.

    Authorized Cluster Endpoint​

    Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.

    note

    The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher used RKE to provision the cluster. It is not available for clusters in a hosted Kubernetes provider, such as Amazon's EKS.

    This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the controlplane role and the default Kubernetes self signed certificates.

    For more detail on how an authorized cluster endpoint works and why it is used, refer to the architecture section.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Node Pools​

    For information on using the Rancher UI to set up node pools in an RKE cluster, refer to this page.

    NGINX Ingress​

    If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use NGINX Ingress within the cluster.

    Metrics Server Monitoring​

    Option to enable or disable Metrics Server.

    Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal.

    Pod Security Policy Support​

    Enables pod security policies for the cluster. After enabling this option, choose a policy using the Default Pod Security Policy drop-down.

    You must have an existing Pod Security Policy configured before you can use this option.

    Docker Version on Nodes​

    Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support.

    If you choose to require a supported Docker version, Rancher will stop pods from running on nodes that don't have a supported Docker version installed.

    For details on which Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    Docker Root Directory​

    If the nodes you are adding to the cluster have Docker configured with a non-default Docker Root Directory (default is /var/lib/docker), specify the correct Docker Root Directory in this option.

    Default Pod Security Policy​

    If you enable Pod Security Policy Support, use this drop-down to choose the pod security policy that's applied to the cluster.

    Node Port Range​

    Option to change the range of ports that can be used for NodePort services. Default is 30000-32767.

    Recurring etcd Snapshots​

    Option to enable or disable recurring etcd snapshots.

    Agent Environment Variables​

    Option to set environment variables for rancher agents. The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables can be set using agent environment variables.

    Updating ingress-nginx​

    Clusters that were created before Kubernetes 1.16 will have an ingress-nginx updateStrategy of OnDelete. Clusters that were created with Kubernetes 1.16 or newer will have RollingUpdate.

    If the updateStrategy of ingress-nginx is OnDelete, you will need to delete these pods to get the correct version for your deployment.

    RKE Cluster Config File Reference​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration. The system_images option is not supported when creating a cluster with the Rancher UI or API.

    For the complete reference for configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    Config File Structure in Rancher​

    RKE (Rancher Kubernetes Engine) is the tool that Rancher uses to provision Kubernetes clusters. Rancher's cluster config files used to have the same structure as RKE config files, but the structure changed so that in Rancher, RKE cluster config items are separated from non-RKE config items. Therefore, configuration for your cluster needs to be nested under the rancher_kubernetes_engine_config directive in the cluster config file. Cluster config files created with earlier versions of Rancher will need to be updated for this format. An example cluster config file is included below.

    Example Cluster Config File
    #
    # Cluster Config
    #
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config: # Your RKE template config goes here.
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false
    windows_prefered_cluster: false

    Default DNS provider​

    The table below indicates what DNS provider is deployed by default. See RKE documentation on DNS provider for more information how to configure a different DNS provider. CoreDNS can only be used on Kubernetes v1.12.0 and higher.

    Rancher versionKubernetes versionDefault DNS provider
    v2.2.5 and higherv1.14.0 and higherCoreDNS
    v2.2.5 and higherv1.13.x and lowerkube-dns
    v2.2.4 and loweranykube-dns

    Rancher Specific Parameters in YAML​

    Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML):

    docker_root_dir​

    See Docker Root Directory.

    enable_cluster_monitoring​

    Option to enable or disable Cluster Monitoring.

    enable_network_policy​

    Option to enable or disable Project Network Isolation.

    Project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.

    local_cluster_auth_endpoint​

    See Authorized Cluster Endpoint.

    Example:

    local_cluster_auth_endpoint:
      enabled: true
      fqdn: "FQDN"
      ca_certs: |-
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----

    Custom Network Plug-in​

    You can add a custom network plug-in by using the user-defined add-on functionality of RKE. You define any add-on that you want deployed after the Kubernetes cluster is deployed.

    There are two ways that you can specify an add-on:

    For an example of how to configure a custom network plug-in by editing the cluster.yml, refer to the RKE documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.html b/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.html index 67aea7b212b..87ce2785413 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.html @@ -5,13 +5,13 @@ RKE2 Cluster Configuration Reference | Rancher Manager - +
    Version: v2.6

    RKE2 Cluster Configuration Reference

    This section covers the configuration options that are available in Rancher for a new or existing RKE2 Kubernetes cluster.

    Overview​

    You can configure the Kubernetes options in one of the two following ways:

    • Rancher UI: Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
    • Cluster Config File: Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE2 config file. Using a config file allows you to set many additional options available for an RKE2 installation.

    Editing Clusters with a Form in the Rancher UI​

    To edit your cluster,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster you want to configure and click ⋮ > Edit Config.

    Editing Clusters with YAML​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE2 config file. Using a config file allows you to set any of the options available in an RKE2 installation by specifying them in YAML.

    To edit an RKE2 config file directly from the Rancher UI,

    1. Click ☰ > Cluster Management.
    2. Go to the cluster you want to configure and click ⋮ > Edit as YAML.
    3. Edit the RKE options under the rkeConfig directive.

    Configuration Options in the Rancher UI​

    tip

    Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE2 cluster configuration file in YAML. For the complete reference of configurable options for RKE2 Kubernetes clusters in YAML, see the RKE2 documentation.

    Machine Pool​

    This subsection covers the generic machine pool configurations. For infrastructure provider specific, configurations refer to the following pages:

    Pool Name​

    The name of the machine pool.

    Machine Count​

    The number of machines in the pool.

    Roles​

    Option to assign etcd, control plane, and worker roles to nodes.

    Advanced​

    Auto Replace​

    The duration nodes can be unreachable before they are automatically deleted and replaced.

    Drain Before Delete​

    Enables draining nodes by evicting all pods before the node is deleted.

    Kubernetes Node Labels​

    Add labels to nodes to help with organization and object selection.

    For details on label syntax requirements, see the Kubernetes documentation.

    Taints​

    Add taints to nodes, which can be used to prevent pods from being scheduled to or executed on nodes, unless the pods have matching tolerations.

    Cluster Configuration​

    Basics​

    Kubernetes Version​

    The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on hyperkube.

    For more detail, see Upgrading Kubernetes.

    Container Network Provider​

    The Network Provider that the cluster uses.

    caution

    After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you to tear down the entire cluster and all its applications.

    Out of the box, Rancher is compatible with the following network providers:

    * When using project network isolation in the Cilium CNI, it is possible to enable cross-node ingress routing. Click the CNI provider docs to learn more.

    For more details on the different networking providers and how to configure them, please view our RKE2 documentation.

    Dual-stack Networking​

    Dual-stack networking is supported for all CNI providers. To configure RKE2 in dual-stack mode, set valid IPv4/IPv6 CIDRs for your Cluster CIDR and/or Service CIDR.

    Additional Configuration​

    When using cilium or multus,cilium as your container network interface provider, ensure the Enable IPv6 Support option is also enabled.

    Cloud Provider​

    You can configure a Kubernetes cloud provider. If you want to use dynamically provisioned volumes and storage in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the aws cloud provider.

    note

    If the cloud provider you want to use is not listed as an option, you will need to use the config file option to configure the cloud provider. Please reference this documentation on how to configure the cloud provider.

    Default Pod Security Policy​

    Choose the default pod security policy for the cluster. Please refer to the RKE2 documentation on the specifications of each available policy.

    Worker CIS Profile​

    Select a CIS benchmark to validate the system configuration against.

    Project Network Isolation​

    If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.

    Project network isolation is available if you are using any RKE2 network plugin that supports the enforcement of Kubernetes network policies, such as Canal.

    CoreDNS​

    By default, CoreDNS is installed as the default DNS provider. If CoreDNS is not installed, an alternate DNS provider must be installed yourself. Refer to the RKE2 documentation for additional CoreDNS configurations.

    NGINX Ingress​

    If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use NGINX Ingress within the cluster. Refer to the RKE2 documentation for additional configuration options.

    Refer to the RKE2 documentation for additional configuration options.

    Metrics Server​

    Option to enable or disable Metrics Server.

    Each cloud provider capable of launching a cluster using RKE2 can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal.

    Add-On Config​

    Additional Kubernetes manifests, managed as an Add-on, to apply to the cluster on startup. Refer to the RKE2 documentation for details.

    Agent Environment Vars​

    Option to set environment variables for Rancher agents. The environment variables can be set using key value pairs. Refer to the RKE2 documentation for more details.

    etcd​

    Automatic Snapshots​

    Option to enable or disable recurring etcd snapshots. If enabled, users have the option to configure the frequency of snapshots. For details, refer to the RKE2 documentation. Note that with RKE2, snapshots are stored on each etcd node. This varies from RKE1 which only stores one snapshot per cluster.

    Metrics​

    Option to choose whether to expose etcd metrics to the public or only within the cluster.

    Networking​

    Cluster CIDR​

    IPv4 and/or IPv6 network CIDRs to use for pod IPs (default: 10.42.0.0/16).

    Dual-stack Networking​

    To configure dual-stack mode, enter a valid IPv4/IPv6 CIDR. For example 10.42.0.0/16,2001:cafe:42:0::/56.

    Additional configuration is required when using cilium or multus,cilium as your container network interface provider.

    Service CIDR​

    IPv4/IPv6 network CIDRs to use for service IPs (default: 10.43.0.0/16).

    Dual-stack Networking​

    To configure dual-stack mode, enter a valid IPv4/IPv6 CIDR. For example 10.42.0.0/16,2001:cafe:42:0::/56.

    Additional configuration is required when using cilium or multus,cilium as your container network interface provider.

    Cluster DNS​

    IPv4 Cluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10).

    Cluster Domain​

    Select the domain for the cluster. The default is cluster.local.

    NodePort Service Port Range​

    Option to change the range of ports that can be used for NodePort services. The default is 30000-32767.

    TLS Alternate Names​

    Add additional hostnames or IPv4/IPv6 addresses as Subject Alternative Names on the server TLS cert.

    Authorized Cluster Endpoint​

    Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.

    This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the controlplane role and the default Kubernetes self signed certificates.

    For more detail on how an authorized cluster endpoint works and why it is used, refer to the architecture section.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Registries​

    Select the image repository to pull Rancher images from. For more details and configuration options, see the RKE2 documentation.

    Upgrade Strategy​

    Control Plane Concurrency​

    Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.

    Worker Concurrency​

    Select how many nodes can be upgraded at the same time. Can be a fixed number or percentage.

    Drain Nodes (Control Plane)​

    Option to remove all pods from the node prior to upgrading.

    Drain Nodes (Worker Nodes)​

    Option to remove all pods from the node prior to upgrading.

    Advanced​

    Option to set kubelet options for different nodes. For available options, refer to the Kubernetes documentation.

    Cluster Config File Reference​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create a config file. Using a config file allows you to set the options available in an RKE2 installation, including those already listed in Configuration Options in the Rancher UI, as well as Rancher-specific parameters.

    Example Cluster Config File Snippet
    spec:
      cloudCredentialSecretName: cattle-global-data:cc-s879v
      kubernetesVersion: v1.23.6+rke2r2
      localClusterAuthEndpoint: {}
      rkeConfig:
        chartValues:
          rke2-calico: {}
        etcd:
          snapshotRetention: 5
          snapshotScheduleCron: 0 */5 * * *
        machineGlobalConfig:
          cni: calico
          disable-kube-proxy: false
          etcd-expose-metrics: false
          profile: null
        machinePools:
        - controlPlaneRole: true
          etcdRole: true
          machineConfigRef:
            kind: Amazonec2Config
            name: nc-test-pool1-pwl5h
          name: pool1
          quantity: 1
          unhealthyNodeTimeout: 0s
          workerRole: true
        machineSelectorConfig:
        - config:
            protect-kernel-defaults: false
        registries: {}
        upgradeStrategy:
          controlPlaneConcurrency: "1"
          controlPlaneDrainOptions:
            deleteEmptyDirData: true
            enabled: true
            gracePeriod: -1
            ignoreDaemonSets: true
            timeout: 120
          workerConcurrency: "1"
          workerDrainOptions:
            deleteEmptyDirData: true
            enabled: true
            gracePeriod: -1
            ignoreDaemonSets: true
            timeout: 120

    chartValues​

    Option to specify the values for the system charts installed by RKE2/k3s.

    Example:

    chartValues:
        chart-name:
            key: value

    machineGlobalConfig​

    The RKE2/K3s configurations are nested under the machineGlobalConfig directive. Any configuration change made here will apply to every node. The configuration options available in the standalone version of RKE2 can be applied here.

    Example:

    machineGlobalConfig:
        etcd-arg:
            - key1=value1
            - key2=value2

    machineSelectorConfig​

    This is the same as machineGlobalConfig except that a label selector can be specified with the configuration. The configuration will only be applied to nodes that match the provided label selector.

    Multiple config entries are allowed, each specifying their own machineLabelSelector. A user can specify matchExpressions, matchLabels, both, or neither. Omitting the machineLabelSelector section of this has the same effect as putting the config in the machineGlobalConfig section.

    Example:

    machineSelectorConfig
      - config:
          config-key: config-value
        machineLabelSelector:
          matchExpressions:
            - key: example-key
              operator: string # Valid operators are In, NotIn, Exists and DoesNotExist.
              values:
                - example-value1
                - example-value2
          matchLabels:
            key1: value1
            key2: value2
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html b/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html index 56f3cbbcfcf..ec7bac77f5d 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html @@ -5,13 +5,13 @@ Syncing | Rancher Manager - +
    Version: v2.6

    Syncing

    Syncing is the feature for EKS and GKE clusters that causes Rancher to update the clusters' values so they are up to date with their corresponding cluster object in the hosted Kubernetes provider. This enables Rancher to not be the sole owner of a hosted cluster’s state. Its largest limitation is that processing an update from Rancher and another source at the same time or within 5 minutes of one finishing may cause the state from one source to completely overwrite the other.

    How it works​

    There are two fields on the Rancher Cluster object that must be understood to understand how syncing works:

    1. The config object for the cluster, located on the Spec of the Cluster:

      • For EKS, the field is called EKSConfig
      • For GKE, the field is called GKEConfig

    2. The UpstreamSpec object

      • For EKS, this is located on the EKSStatus field on the Status of the Cluster.
      • For GKE, this is located on the GKEStatus field on the Status of the Cluster.

    The struct types that define these objects can be found in their corresponding operator projects:

    All fields with the exception of the cluster name, the location (region or zone), Imported, and the cloud credential reference, are nillable on this Spec object.

    The EKSConfig or GKEConfig represents desired state for its non-nil values. Fields that are non-nil in the config object can be thought of as “managed". When a cluster is created in Rancher, all fields are non-nil and therefore “managed”. When a pre-existing cluster is registered in rancher all nillable fields are nil and are not “managed”. Those fields become managed once their value has been changed by Rancher.

    UpstreamSpec represents the cluster as it is in the hosted Kubernetes provider and is refreshed on an interval of 5 minutes. After the UpstreamSpec has been refreshed, Rancher checks if the cluster has an update in progress. If it is updating, nothing further is done. If it is not currently updating, any “managed” fields on EKSConfig or GKEConfig are overwritten with their corresponding value from the recently updated UpstreamSpec.

    The effective desired state can be thought of as the UpstreamSpec + all non-nil fields in the EKSConfig or GKEConfig. This is what is displayed in the UI.

    If Rancher and another source attempt to update a cluster at the same time or within the 5 minute refresh window of an update finishing, then it is likely any “managed” fields can be caught in a race condition. To use EKS as an example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console, then finishes at 11:01, and then tags are updated from Rancher before 11:05 the value will likely be overwritten. This would also occur if tags were updated while the cluster was processing the update. If the cluster was registered and the PrivateAccess fields was nil then this issue should not occur in the aforementioned case.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html b/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html index 6b4cc2234f6..9c684708e16 100644 --- a/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html +++ b/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html @@ -5,13 +5,13 @@ Rancher Agent Options | Rancher Manager - +
    Version: v2.6

    Rancher Agent Options

    Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to create a cluster with custom nodes and add the options to the generated docker run command when adding a node.

    For an overview of how Rancher communicates with downstream clusters using node agents, refer to the architecture section.

    General options​

    ParameterEnvironment variableDescription
    --serverCATTLE_SERVERThe configured Rancher server-url setting which the agent connects to
    --tokenCATTLE_TOKENToken that is needed to register the node in Rancher
    --ca-checksumCATTLE_CA_CHECKSUMThe SHA256 checksum of the configured Rancher cacerts setting to validate
    --node-nameCATTLE_NODE_NAMEOverride the hostname that is used to register the node (defaults to hostname -s)
    --labelCATTLE_NODE_LABELAdd node labels to the node. For multiple labels, pass additional --label options. (--label key=value)
    --taintsCATTLE_NODE_TAINTSAdd node taints to the node. For multiple taints, pass additional --taints options. (--taints key=value:effect)

    Role options​

    ParameterEnvironment variableDescription
    --all-rolesALL=trueApply all roles (etcd,controlplane,worker) to the node
    --etcdETCD=trueApply the role etcd to the node
    --controlplaneCONTROL=trueApply the role controlplane to the node
    --workerWORKER=trueApply the role worker to the node

    IP address options​

    ParameterEnvironment variableDescription
    --addressCATTLE_ADDRESSThe IP address the node will be registered with (defaults to the IP used to reach 8.8.8.8)
    --internal-addressCATTLE_INTERNAL_ADDRESSThe IP address used for inter-host communication on a private network

    Dynamic IP address options​

    For automation purposes, you can't have a specific IP address in a command as it has to be generic to be used for every node. For this, we have dynamic IP address options. They are used as a value to the existing IP address options. This is supported for --address and --internal-address.

    ValueExampleDescription
    Interface name--address eth0The first configured IP address will be retrieved from the given interface
    ipify--address ipifyValue retrieved from https://api.ipify.org will be used
    awslocal--address awslocalValue retrieved from http://169.254.169.254/latest/meta-data/local-ipv4 will be used
    awspublic--address awspublicValue retrieved from http://169.254.169.254/latest/meta-data/public-ipv4 will be used
    doprivate--address doprivateValue retrieved from http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address will be used
    dopublic--address dopublicValue retrieved from http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address will be used
    azprivate--address azprivateValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text will be used
    azpublic--address azpublicValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text will be used
    gceinternal--address gceinternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip will be used
    gceexternal--address gceexternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip will be used
    packetlocal--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/local-ipv4 will be used
    packetpublic--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/public-ipv4 will be used
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/configure-openldap/openldap-config-reference.html b/reference-guides/configure-openldap/openldap-config-reference.html index f898be47b9e..b25fa69436e 100644 --- a/reference-guides/configure-openldap/openldap-config-reference.html +++ b/reference-guides/configure-openldap/openldap-config-reference.html @@ -5,13 +5,13 @@ OpenLDAP Configuration Reference | Rancher Manager - +
    Version: v2.6

    OpenLDAP Configuration Reference

    This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.

    For further details on configuring OpenLDAP, refer to the official documentation.

    Before you proceed with the configuration, please familiarize yourself with the concepts of External Authentication Configuration and Principal Users.

    Background: OpenLDAP Authentication Flow​

    1. When a user attempts to login with LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
    2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
    3. Once the user has been found, they are authenticated with another LDAP bind request using the user's DN and provided password.
    4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.

    OpenLDAP Server Configuration

    You will need to enter the address, port, and protocol to connect to your OpenLDAP server. 389 is the standard port for insecure traffic, 636 for TLS traffic.

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

    OpenLDAP Server Parameters
    ParameterDescription
    HostnameSpecify the hostname or IP address of the OpenLDAP server
    PortSpecify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
    TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate.
    Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the server unreachable.
    Service Account Distinguished NameEnter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries.
    Service Account PasswordThe password for the service account.
    User Search BaseEnter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
    Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".

    User/Group Schema Configuration

    If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the Customize Schema section to match it.

    Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.

    If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

    User Schema Configuration​

    The table below details the parameters for the user schema configuration.

    User Schema Configuration Parameters
    ParameterDescription
    Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Username AttributeThe user attribute whose value is suitable as a display name.
    Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically uid.
    User Member AttributeThe user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of memberOf or isMemberOf.
    Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol.
    User Enabled AttributeIf the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty.
    Disabled Status BitmaskThis is the value for a disabled/locked user account. The parameter is ignored if User Enabled Attribute is empty.

    Group Schema Configuration​

    The table below details the parameters for the group schema configuration.

    Group Schema Configuration Parameters
    ParameterDescription
    Object ClassThe name of the object class used for group entries in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Name AttributeThe group attribute whose value is suitable for a display name.
    Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
    Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
    Search AttributeAttribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema Search Attribute.
    Group DN AttributeThe name of the group attribute whose format matches the values in the user's group membership attribute. See User Member Attribute.
    Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/installation-references/feature-flags.html b/reference-guides/installation-references/feature-flags.html index c5752572753..3e3413e2d66 100644 --- a/reference-guides/installation-references/feature-flags.html +++ b/reference-guides/installation-references/feature-flags.html @@ -5,13 +5,13 @@ Feature Flags | Rancher Manager - +
    Version: v2.6

    Feature Flags

    Feature flags were introduced to allow you to try experimental features that are not enabled by default.

    To learn about feature values and how to enable features, refer here.

    note

    There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.

    The following is a list of the feature flags available in Rancher:

    • harvester: This feature flag is available starting in v2.6.1. It is used to manage access to the Virtualization Management page where users can navigate directly to Harvester clusters and access the Harvester UI. For more information, see this page.
    • rke2: Used to enable the ability to provision RKE2 clusters. By default, this feature flag is enabled, which allows users to attempt to provision these type of clusters.
    • fleet: The previous fleet feature flag is now required to be enabled as the Fleet capabilities are leveraged within the new provisioning framework. If you had this feature flag disabled in earlier versions, upon upgrading to Rancher v2.6, the flag will automatically be enabled. See this page for more information.
    • continuous-delivery: In Rancher v2.5.x, Fleet came with a GitOps feature that could not be disabled separately from Fleet. In Rancher v2.6, the continuous-delivery feature flag was introduced to allow the GitOps feature of Fleet to be disabled. For more information, see this page..
    • legacy: There are a set of features from previous versions that are slowly being phased out of Rancher for newer iterations of the feature. This is a mix of deprecated features as well as features that will eventually be moved to newer variations in Rancher. By default, this feature flag is disabled for new installations. If you are upgrading from a previous version, this feature flag would be enabled.
    • token-hashing: Used to enable new token-hashing feature. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically using the SHA256 algorithm. Once a token is hashed it cannot be undone. Once this feature flag is enabled, it cannot be disabled. See hashing of tokens for more information.
    • unsupported-storage-drivers: This feature allows unsupported storage drivers.. In other words, it enables types for storage providers and provisioners that are not enabled by default.
    • istio-virtual-service-ui: This feature enables a UI to create, read, update, and delete Istio virtual services and destination rules, which are traffic management features of Istio.
    • multi-cluster-management: Used for multi-cluster provisioning and management of Kubernetes clusters. This feature flag can only be set at install time and not changed afterwards.

    The below table shows the availability and default value for feature flags in Rancher:

    Feature Flag NameDefault ValueStatusAvailable as ofRancher Restart Required?
    istio-virtual-service-uifalseExperimentalv2.3.0
    istio-virtual-service-uitrueGA*v2.3.2
    unsupported-storage-driversfalseExperimentalv2.3.0
    fleettrueGA*v2.5.0
    fleettrueCan no longer be disabledv2.6.0N/A
    continuous-deliverytrueGA*v2.6.0
    token-hashingfalse for new installs, true for upgradesGA*v2.6.0
    legacyfalse for new installs, true for upgradesGA*v2.6.0
    multi-cluster-managementfalseGA*v2.5.0
    harvestertrueExperimentalv2.6.1
    rke2trueExperimentalv2.6.0

    * Generally Available. This feature is included in Rancher and it is not experimental.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/installation-references/helm-chart-options.html b/reference-guides/installation-references/helm-chart-options.html index 9a4bb3730f7..2a5f67ba836 100644 --- a/reference-guides/installation-references/helm-chart-options.html +++ b/reference-guides/installation-references/helm-chart-options.html @@ -5,13 +5,13 @@ Rancher Helm Chart Options | Rancher Manager - +
    Version: v2.6

    Rancher Helm Chart Options

    This page is a configuration reference for the Rancher Helm chart.

    For help choosing a Helm chart version, refer to this page.

    For information on enabling experimental features, refer to this page.

    Common Options​

    OptionDefault ValueDescription
    bootstrapPassword" "string - Set the bootstrap password for the first admin user. After logging in, the admin will need to reset their password. A randomly generated bootstrap password is used if this value is not set.
    hostname" "string - the Fully Qualified Domain Name for your Rancher Server
    ingress.tls.source"rancher"string - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret"
    letsEncrypt.email" "string - Your email address
    letsEncrypt.environment"production"string - Valid options: "staging, production"
    privateCAfalsebool - Set to true if your cert is signed by a private CA

    Advanced Options​

    OptionDefault ValueDescription
    additionalTrustedCAsfalsebool - See Additional Trusted CAs
    addLocal"true"string - Have Rancher detect and import the "local" Rancher server cluster. Note: This option is no longer available in v2.5.0. Consider using the restrictedAdmin option to prevent users from modifying the local cluster.
    antiAffinity"preferred"string - AntiAffinity rule for Rancher pods - "preferred, required"
    auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
    auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
    auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
    auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
    auditLog.maxBackup1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
    auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
    busyboxImage"busybox"string - Image location for busybox image used to collect audit logs
    certmanager.version""string - set cert-manager compatibility
    debugfalsebool - set debug flag on rancher server
    extraEnv[]list - set additional environment variables for Rancher
    imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
    ingress.configurationSnippet""string - Add additional Nginx configuration. Can be used for proxy configuration.
    ingress.extraAnnotations{}map - additional annotations to customize the ingress
    ingress.enabledtrueWhen set to false, Helm will not install a Rancher ingress. Set the option to false to deploy your own ingress.
    letsEncrypt.ingress.class""string - optional ingress class for the cert-manager acmesolver ingress that responds to the Let's Encrypt ACME challenges. Options: traefik, nginx.
    noProxy"127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local,cattle-system.svc"string - comma separated list of hostnames or ip address not to use the proxy
    proxy""string - HTTP[S] proxy server for Rancher
    rancherImage"rancher/rancher"string - rancher image source
    rancherImagePullPolicy"IfNotPresent"string - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent"
    rancherImageTagsame as chart versionstring - rancher/rancher image tag
    replicas3int - Number of Rancher server replicas. Setting to -1 will dynamically choose 1, 2, or 3 based on the number of available nodes in the cluster.
    resources{}map - rancher pod resource requests & limits
    restrictedAdminfalsebool - When this option is set to true, the initial Rancher user has restricted access to the local Kubernetes cluster to prevent privilege escalation. For more information, see the section about the restricted-admin role.
    systemDefaultRegistry""string - private registry to be used for all system container images, e.g., registry.example.com
    tls"ingress"string - See External TLS Termination for details. - "ingress, external"
    useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.

    Bootstrap Password​

    When Rancher starts for the first time, a password is randomly generated for the first admin user. When the admin first logs in to Rancher, the UI shows commands that can be used to retrieve the bootstrap password. The admin needs to run those commands and log in with the bootstrap password. Then Rancher gives the admin an opportunity to reset the password.

    If you want to use a specific bootstrap password instead of a randomly generated one, provide the password.

    --set bootstrapPassword="rancher"

    The password, whether provided or generated, will be stored in a Kubernetes secret. After Rancher is installed, the UI will show instructions for how to retrieve the password using kubectl:

    kubectl get secret --namespace cattle-system bootstrap-secret -o go-template='{{ .data.bootstrapPassword|base64decode}}{{ "\n" }}'

    API Audit Log​

    Enabling the API Audit Log

    You can collect this log as you would any container log. Enable logging for the System Project on the Rancher server cluster.

    --set auditLog.level=1

    By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (rancher-audit-log) will stream the log to stdout. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the hostPath, maxAge, maxBackups, and maxSize options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable logging for the Rancher server cluster or System Project.

    Set the auditLog.destination to hostPath to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to hostPath you may want to adjust the other auditLog parameters for log rotation.

    Setting Extra Environment Variables​

    You can set extra environment variables for Rancher server using extraEnv. This list uses the same name and value keys as the container manifest definitions. Remember to quote the values.

    --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
    --set 'extraEnv[0].value=1.0'

    TLS Settings​

    When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller.

    See TLS settings for more information and options.

    Import local Cluster​

    By default Rancher server will detect and import the local cluster it's running on. User with access to the local cluster will essentially have "root" access to all the clusters managed by Rancher server.

    caution

    If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner.

    If this is a concern in your environment you can set this option to "false" on your initial install.

    This option is only effective on the initial Rancher install. See Issue 16522 for more information.

    --set addLocal="false"

    Customizing your Ingress​

    To customize or use a different ingress with Rancher server you can set your own Ingress annotations.

    Example on setting a custom certificate issuer:

    --set ingress.extraAnnotations.'cert-manager\.io/cluster-issuer'=issuer-name

    Example on setting a static proxy header with ingress.configurationSnippet. This value is parsed like a template so variables can be used.

    --set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};'

    HTTP Proxy​

    Rancher requires internet access for some functionality (helm charts). Use proxy to set your proxy server.

    Add your IP exceptions to the noProxy list. Make sure you add the Pod cluster IP range (default: 10.42.0.0/16), Service cluster IP range (default: 10.43.0.0/16), the internal cluster domains (default: .svc,.cluster.local) and any worker cluster controlplane nodes. Rancher supports CIDR notation ranges in this list.

    --set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
    --set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local"

    Additional Trusted CAs​

    If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.

    --set additionalTrustedCAs=true

    Once the Rancher deployment is created, copy your CA certs in pem format into a file named ca-additional.pem and use kubectl to create the tls-ca-additional secret in the cattle-system namespace.

    kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem=./ca-additional.pem

    Private Registry and Air Gap Installs​

    For details on installing Rancher with a private registry, see the air gap installation docs.

    External TLS Termination

    We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

    You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the --set tls=external option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.

    note

    If you are using a Private CA signed certificate, add --set privateCA=true and see Adding TLS Secrets - Using a Private CA Signed Certificate to add the CA cert for Rancher.

    Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

    Configuring Ingress for External TLS when Using NGINX v0.25​

    In NGINX v0.25, the behavior of NGINX has changed regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the cluster.yml to enable the use-forwarded-headers option for ingress:

    ingress:
      provider: nginx
      options:
        use-forwarded-headers: 'true'

    Required Headers​

    • Host
    • X-Forwarded-Proto
    • X-Forwarded-Port
    • X-Forwarded-For
    • Read Timeout: 1800 seconds
    • Write Timeout: 1800 seconds
    • Connect Timeout: 30 seconds

    Health Checks​

    Rancher will respond 200 to health checks on the /healthz endpoint.

    Example NGINX config​

    This NGINX configuration is tested on NGINX 1.14.

    caution

    This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

    • Replace IP_NODE1, IP_NODE2 and IP_NODE3 with the IP addresses of the nodes in your cluster.
    • Replace both occurrences of FQDN to the DNS name for Rancher.
    • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
    worker_processes 4;
    worker_rlimit_nofile 40000;

    events {
        worker_connections 8192;
    }

    http {
        upstream rancher {
            server IP_NODE_1:80;
            server IP_NODE_2:80;
            server IP_NODE_3:80;
        }

        map $http_upgrade $connection_upgrade {
            default Upgrade;
            ''      close;
        }

        server {
            listen 443 ssl http2;
            server_name FQDN;
            ssl_certificate /certs/fullchain.pem;
            ssl_certificate_key /certs/privkey.pem;

            location / {
                proxy_set_header Host $host;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_pass http://rancher;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                proxy_read_timeout 900s;
                proxy_buffering off;
            }
        }

        server {
            listen 80;
            server_name FQDN;
            return 301 https://$server_name$request_uri;
        }
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/installation-references/tls-settings.html b/reference-guides/installation-references/tls-settings.html index 72f850dd566..8c9ac302926 100644 --- a/reference-guides/installation-references/tls-settings.html +++ b/reference-guides/installation-references/tls-settings.html @@ -5,13 +5,13 @@ TLS Settings | Rancher Manager - +
    Version: v2.6

    TLS Settings

    Changing the default TLS settings depends on the chosen installation method.

    Running Rancher in a highly available Kubernetes cluster

    When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller:

    Running Rancher in a single Docker container

    The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables:

    ParameterDescriptionDefaultAvailable options
    CATTLE_TLS_MIN_VERSIONMinimum TLS version1.21.0, 1.1, 1.2, 1.3
    CATTLE_TLS_CIPHERSAllowed TLS cipher suitesTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    		See Golang tls constants
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/kubernetes-concepts.html b/reference-guides/kubernetes-concepts.html index 7290e7d5369..8795abe0c7d 100644 --- a/reference-guides/kubernetes-concepts.html +++ b/reference-guides/kubernetes-concepts.html @@ -5,13 +5,13 @@ Kubernetes Concepts | Rancher Manager - +
    Version: v2.6

    Kubernetes Concepts

    This page explains concepts related to Kubernetes that are important for understanding how Rancher works. The descriptions below provide a simplified overview of Kubernetes components. For more details, refer to the official documentation on Kubernetes components.

    About Docker​

    Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. Docker Hub is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes.

    note

    Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes.

    About Kubernetes​

    Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management.

    What is a Kubernetes Cluster?​

    A cluster is a group of computers that work together as a single system.

    A Kubernetes Cluster is a cluster that uses the Kubernetes container-orchestration system to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations.

    Roles for Nodes in Kubernetes Clusters​

    Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: etcd nodes, control plane nodes, and worker nodes.

    A Kubernetes cluster consists of at least one etcd, controlplane, and worker node.

    etcd Nodes​

    Rancher uses etcd as a data store in both single node and high-availability installations. In Kubernetes, etcd is also a role for nodes that store the cluster state.

    The state of a Kubernetes cluster is maintained in etcd. The etcd nodes run the etcd database.

    The etcd database component is a distributed key-value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. It is recommended to run etcd on multiple nodes so that there's always a backup available for failover.

    Although you can run etcd on just one node, etcd requires a majority of nodes, a quorum, to agree on updates to the cluster state. The cluster should always contain enough healthy etcd nodes to form a quorum. For a cluster with n members, a quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for a quorum.

    Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters.

    Controlplane Nodes​

    Controlplane nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although three or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles.

    Worker Nodes​

    Each worker node runs the following:

    • Kubelets: An agent that monitors the state of the node, ensuring your containers are healthy.
    • Workloads: The containers and pods that hold your apps, as well as other types of deployments.

    Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads.

    About Helm​

    For high-availability installations of Rancher, Helm is the tool used to install Rancher on a Kubernetes cluster.

    Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

    For more information on service accounts and cluster role binding, refer to the Kubernetes documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/monitoring-v2-configuration/examples.html b/reference-guides/monitoring-v2-configuration/examples.html index 2172febe188..381d8db7473 100644 --- a/reference-guides/monitoring-v2-configuration/examples.html +++ b/reference-guides/monitoring-v2-configuration/examples.html @@ -5,13 +5,13 @@ Examples | Rancher Manager - +
    Version: v2.6

    Examples

    ServiceMonitor​

    An example ServiceMonitor custom resource can be found here.

    PodMonitor​

    An example PodMonitor can be found here. An example Prometheus resource that refers to it can be found here.

    PrometheusRule​

    For users who are familiar with Prometheus, a PrometheusRule contains the alerting and recording rules that you would normally place in a Prometheus rule file.

    For a more fine-grained application of PrometheusRules within your cluster, the ruleSelector field on a Prometheus resource allows you to select which PrometheusRules should be loaded onto Prometheus based on the labels attached to the PrometheusRules resources.

    An example PrometheusRule is on this page.

    Alertmanager Config​

    For an example configuration, refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/monitoring-v2-configuration/helm-chart-options.html b/reference-guides/monitoring-v2-configuration/helm-chart-options.html index 7aa13251f46..7e7887f6d22 100644 --- a/reference-guides/monitoring-v2-configuration/helm-chart-options.html +++ b/reference-guides/monitoring-v2-configuration/helm-chart-options.html @@ -5,13 +5,13 @@ Helm Chart Options | Rancher Manager - +
    Version: v2.6

    Helm Chart Options

    Configuring Resource Limits and Requests​

    The resource requests and limits can be configured when installing rancher-monitoring.

    The default values are in the values.yaml in the rancher-monitoring Helm chart.

    The default values in the table below are the minimum required resource limits and requests.

    Resource NameMemory LimitCPU LimitMemory RequestCPU Request
    alertmanager500Mi1000m100Mi100m
    grafana200Mi200m100Mi100m
    kube-state-metrics subchart200Mi100m130Mi100m
    prometheus-node-exporter subchart50Mi200m30Mi100m
    prometheusOperator500Mi200m100Mi100m
    prometheus2500Mi1000m1750Mi750m
    Total3950Mi2700m2210Mi1250m

    At least 50Gi storage is recommended.

    Trusted CA for Notifiers​

    If you need to add a trusted CA to your notifier, follow these steps:

    1. Create the cattle-monitoring-system namespace.
    2. Add your trusted CA secret to the cattle-monitoring-system namespace.
    3. Deploy or upgrade the rancher-monitoring Helm chart. In the chart options, reference the secret in Alerting > Additional Secrets.

    Result: The default Alertmanager custom resource will have access to your trusted CA.

    Additional Scrape Configurations​

    If the scrape configuration you want cannot be specified via a ServiceMonitor or PodMonitor at the moment, you can provide an additionalScrapeConfigSecret on deploying or upgrading rancher-monitoring.

    A scrape_config section specifies a set of targets and parameters describing how to scrape them. In the general case, one scrape configuration specifies a single job.

    An example of where this might be used is with Istio. For more information, see this section.

    Configuring Applications Packaged within Monitoring v2​

    We deploy kube-state-metrics and node-exporter with monitoring v2. Node exporter are deployed as DaemonSets. In the monitoring v2 helm chart, in the values.yaml, each of the things are deployed as sub charts.

    We also deploy grafana which is not managed by prometheus.

    If you look at what the helm chart is doing like in kube-state-metrics, there are plenty more values that you can set that aren’t exposed in the top level chart.

    But in the top level chart you can add values that override values that exist in the sub chart.

    Increase the Replicas of Alertmanager​

    As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret. For more information on the Alertmanager Config Secret, refer to this section.

    Configuring the Namespace for a Persistent Grafana Dashboard​

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the rancher-monitoring Helm chart:

    grafana.sidecar.dashboards.searchNamespace=ALL

    Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in grafana.dashboards.namespace, which defaults to cattle-dashboards.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/monitoring-v2-configuration/receivers.html b/reference-guides/monitoring-v2-configuration/receivers.html index 667d921cbb0..a461dc05dd9 100644 --- a/reference-guides/monitoring-v2-configuration/receivers.html +++ b/reference-guides/monitoring-v2-configuration/receivers.html @@ -5,13 +5,13 @@ Receiver Configuration | Rancher Manager - +
    Version: v2.6

    Receiver Configuration

    The Alertmanager Config Secret contains the configuration of an Alertmanager instance that sends out notifications based on alerts it receives from Prometheus.

    note

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    Creating Receivers in the Rancher UI​

    Prerequisites:
    • The monitoring application needs to be installed.
    • If you configured monitoring with an existing Alertmanager Secret, it must have a format that is supported by Rancher's UI. Otherwise you will only be able to make changes based on modifying the Alertmanager Secret directly. Note: We are continuing to make enhancements to what kinds of Alertmanager Configurations we can support using the Routes and Receivers UI, so please file an issue if you have a request for a feature enhancement.

    To create notification receivers in the Rancher UI,

    1. Go to the cluster where you want to create receivers. Click Monitoring -> Alerting -> AlertManagerConfigs.
    2. Click Create.
    3. Click Add Receiver.
    4. Enter a Name for the receiver.
    5. Configure one or more providers for the receiver. For help filling out the forms, refer to the configuration options below.
    6. Click Create.

    Result: Alerts can be configured to send notifications to the receiver(s).

    Receiver Configuration​

    The notification integrations are configured with the receiver, which is explained in the Prometheus documentation.

    Native vs. Non-native Receivers​

    By default, AlertManager provides native integration with some receivers, which are listed in this section. All natively supported receivers are configurable through the Rancher UI.

    For notification mechanisms not natively supported by AlertManager, integration is achieved using the webhook receiver. A list of third-party drivers providing such integrations can be found here. Access to these drivers, and their associated integrations, is provided through the Alerting Drivers app. Once enabled, configuring non-native receivers can also be done through the Rancher UI.

    Currently the Rancher Alerting Drivers app provides access to the following integrations:

    The following types of receivers can be configured in the Rancher UI:

    The custom receiver option can be used to configure any receiver in YAML that cannot be configured by filling out the other forms in the Rancher UI.

    Slack​

    FieldTypeDescription
    URLStringEnter your Slack webhook URL. For instructions to create a Slack webhook, see the Slack documentation.
    Default ChannelStringEnter the name of the channel that you want to send alert notifications in the following format: #<channelname>.
    Proxy URLStringProxy for the webhook notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Email​

    FieldTypeDescription
    Default Recipient AddressStringThe email address that will receive notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    SMTP options:

    FieldTypeDescription
    SenderStringEnter an email address available on your SMTP mail server that you want to send the notification from.
    HostStringEnter the IP address or hostname for your SMTP server. Example: smtp.email.com.
    Use TLSBoolUse TLS for encryption.
    UsernameStringEnter a username to authenticate with the SMTP server.
    PasswordStringEnter a password to authenticate with the SMTP server.

    PagerDuty​

    FieldTypeDescription
    Integration TypeStringEvents API v2 or Prometheus.
    Default Integration KeyStringFor instructions to get an integration key, see the PagerDuty documentation.
    Proxy URLStringProxy for the PagerDuty notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Opsgenie​

    FieldDescription
    API KeyFor instructions to get an API key, refer to the Opsgenie documentation.
    Proxy URLProxy for the Opsgenie notifications.
    Enable Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Opsgenie Responders:

    FieldTypeDescription
    TypeStringSchedule, Team, User, or Escalation. For more information on alert responders, refer to the Opsgenie documentation.
    Send ToStringId, Name, or Username of the Opsgenie recipient.

    Webhook​

    FieldDescription
    URLWebhook URL for the app of your choice.
    Proxy URLProxy for the webhook notification.
    Enable Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Custom​

    The YAML provided here will be directly appended to your receiver within the Alertmanager Config Secret.

    Teams​

    Enabling the Teams Receiver for Rancher Managed Clusters​

    The Teams receiver is not a native receiver and must be enabled before it can be used. You can enable the Teams receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the Teams option selected.

    1. In the Rancher UI, go to the cluster where you want to install rancher-alerting-drivers and click Apps & Marketplace.
    2. Click the Alerting Drivers app.
    3. Click the Helm Deploy Options tab.
    4. Select the Teams option and click Install.
    5. Take note of the namespace used as it will be required in a later step.

    Configure the Teams Receiver​

    The Teams receiver can be configured by updating its ConfigMap. For example, the following is a minimal Teams receiver configuration.

    [Microsoft Teams]
    teams-instance-1: https://your-teams-webhook-url

    When configuration is complete, add the receiver using the steps in this section.

    Use the example below as the URL where:

    • ns-1 is replaced with the namespace where the rancher-alerting-drivers app is installed
    url: http://rancher-alerting-drivers-prom2teams.ns-1.svc:8089/v2/teams-instance-1

    SMS​

    Enabling the SMS Receiver for Rancher Managed Clusters​

    The SMS receiver is not a native receiver and must be enabled before it can be used. You can enable the SMS receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the SMS option selected.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to install rancher-alerting-drivers and click Explore.
    3. In the left navigation bar, click
    4. Click the Alerting Drivers app.
    5. Click the Helm Deploy Options tab
    6. Select the SMS option and click Install.
    7. Take note of the namespace used as it will be required in a later step.

    Configure the SMS Receiver​

    The SMS receiver can be configured by updating its ConfigMap. For example, the following is a minimal SMS receiver configuration.

    providers:
      telegram:
        token: 'your-token-from-telegram'

    receivers:
    - name: 'telegram-receiver-1'
      provider: 'telegram'
      to:
        - '123456789'

    When configuration is complete, add the receiver using the steps in this section.

    Use the example below as the name and URL, where:

    • the name assigned to the receiver, e.g. telegram-receiver-1, must match the name in the receivers.name field in the ConfigMap, e.g. telegram-receiver-1
    • ns-1 in the URL is replaced with the namespace where the rancher-alerting-drivers app is installed
    name: telegram-receiver-1
    url http://rancher-alerting-drivers-sachet.ns-1.svc:9876/alert

    Configuring Multiple Receivers​

    By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.

    It is also possible to send alerts to multiple notification systems. One way is to configure the Receiver using custom YAML, in which case you can add the configuration for multiple notification systems, as long as you are sure that both systems should receive the same messages.

    You can also set up multiple receivers by using the continue option for a route, so that the alerts sent to a receiver continue being evaluated in the next level of the routing tree, which could contain another receiver.

    Example Alertmanager Configs​

    Slack​

    To set up notifications via Slack, the following Alertmanager Config YAML can be placed into the alertmanager.yaml key of the Alertmanager Config Secret, where the api_url should be updated to use your Webhook URL from Slack:

    route:
      group_by: ['job']
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 3h
      receiver: 'slack-notifications'
    receivers:
    - name: 'slack-notifications'
      slack_configs:
      - send_resolved: true
        text: '{{ template "slack.rancher.text" . }}'
        api_url: <user-provided slack webhook url here>
    templates:
    - /etc/alertmanager/config/*.tmpl

    PagerDuty​

    To set up notifications via PagerDuty, use the example below from the PagerDuty documentation as a guideline. This example sets up a route that captures alerts for a database service and sends them to a receiver linked to a service that will directly notify the DBAs in PagerDuty, while all other alerts will be directed to a default receiver with a different PagerDuty integration key.

    The following Alertmanager Config YAML can be placed into the alertmanager.yaml key of the Alertmanager Config Secret. The service_key should be updated to use your PagerDuty integration key and can be found as per the "Integrating with Global Event Routing" section of the PagerDuty documentation. For the full list of configuration options, refer to the Prometheus documentation.

    route:
     group_by: [cluster]
     receiver: 'pagerduty-notifications'
     group_interval: 5m
     routes:
      - match:
          service: database
        receiver: 'database-notifcations'

    receivers:
    - name: 'pagerduty-notifications'
      pagerduty_configs:
      - service_key: 'primary-integration-key'

    - name: 'database-notifcations'
      pagerduty_configs:
      - service_key: 'database-integration-key'

    Example Route Config for CIS Scan Alerts​

    While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan.

    For example, the following example route configuration could be used with a Slack receiver named test-cis:

    spec:
      receiver: test-cis
      group_by:
    #    - string
      group_wait: 30s
      group_interval: 30s
      repeat_interval: 30s
      match:
        job: rancher-cis-scan
    #    key: string
      match_re:
        {}
    #    key: string

    For more information on enabling alerting for rancher-cis-benchmark, see this section.

    Trusted CA for Notifiers​

    If you need to add a trusted CA to your notifier, follow the steps in this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/monitoring-v2-configuration/routes.html b/reference-guides/monitoring-v2-configuration/routes.html index 10f7556da0c..8e177c156d6 100644 --- a/reference-guides/monitoring-v2-configuration/routes.html +++ b/reference-guides/monitoring-v2-configuration/routes.html @@ -5,13 +5,13 @@ Route Configuration | Rancher Manager - +
    Version: v2.6

    Route Configuration

    The route configuration is the section of the Alertmanager custom resource that controls how the alerts fired by Prometheus are grouped and filtered before they reach the receiver.

    When a Route is changed, the Prometheus Operator regenerates the Alertmanager custom resource to reflect the changes.

    For more information about configuring routes, refer to the official Alertmanager documentation.

    note

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    Route Restrictions​

    Alertmanager proxies alerts for Prometheus based on its receivers and a routing tree that filters alerts to certain receivers based on labels.

    Alerting drivers proxy alerts for Alertmanager to non-native receivers, such as Microsoft Teams and SMS.

    In the Rancher UI for configuring routes and receivers, you can configure routing trees with one root and then a depth of one more level, for a tree with a depth of two. But if you use a continue route when configuring Alertmanager directly, you can make the tree deeper.

    Each receiver is for one or more notification providers. So if you know that every alert for Slack should also go to PagerDuty, you can configure both in the same receiver.

    Route Configuration​

    Note on Labels and Annotations​

    Labels should be used for identifying information that can affect the routing of notifications. Identifying information about the alert could consist of a container name, or the name of the team that should be notified.

    Annotations should be used for information that does not affect who receives the alert, such as a runbook url or error message.

    Receiver​

    The route needs to refer to a receiver that has already been configured.

    Grouping​

    note

    As of Rancher v2.6.5, Group By now accepts a list of strings instead of key-value pairs. See the upstream documentation for details.

    FieldDefaultDescription
    Group ByN/aList of labels to group by. Labels must not be repeated (unique list). Special label "..." (aggregate by all possible labels), if provided, must be the only element in the list.
    Group Wait30sHow long to wait to buffer alerts of the same group before sending initially.
    Group Interval5mHow long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent.
    Repeat Interval4hHow long to wait before re-sending a given alert that has already been sent.

    Matching​

    The Match field refers to a set of equality matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs to the Rancher UI, they correspond to the YAML in this format:

    match:
      [ <labelname>: <labelvalue>, ... ]

    The Match Regex field refers to a set of regex-matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs in the Rancher UI, they correspond to the YAML in this format:

    match_re:
      [ <labelname>: <regex>, ... ]
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html b/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html index a6ada00e5ce..c12b0fa2ca3 100644 --- a/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html +++ b/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html @@ -5,13 +5,13 @@ ServiceMonitor and PodMonitor Configuration | Rancher Manager - +
    Version: v2.6

    ServiceMonitor and PodMonitor Configuration

    ServiceMonitors and PodMonitors are both pseudo-CRDs that map the scrape configuration of the Prometheus custom resource.

    These configuration objects declaratively specify the endpoints that Prometheus will scrape metrics from.

    ServiceMonitors are more commonly used than PodMonitors, and we recommend them for most use cases.

    note

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    ServiceMonitors​

    This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how groups of Kubernetes services should be monitored.

    When a ServiceMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the ServiceMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the ServiceMonitor.

    Any Services in your cluster that match the labels located within the ServiceMonitor selector field will be monitored based on the endpoints specified on the ServiceMonitor. For more information on what fields can be specified, please look at the spec provided by Prometheus Operator.

    For more information about how ServiceMonitors work, refer to the Prometheus Operator documentation.

    PodMonitors​

    This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how group of pods should be monitored.

    When a PodMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the PodMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the PodMonitor.

    Any Pods in your cluster that match the labels located within the PodMonitor selector field will be monitored based on the podMetricsEndpoints specified on the PodMonitor. For more information on what fields can be specified, please look at the spec provided by Prometheus Operator.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/pipelines/concepts.html b/reference-guides/pipelines/concepts.html index 937998f2a1d..1606f65b095 100644 --- a/reference-guides/pipelines/concepts.html +++ b/reference-guides/pipelines/concepts.html @@ -5,13 +5,13 @@ Concepts | Rancher Manager - +
    Version: v2.6

    Concepts

    The purpose of this page is to explain common concepts and terminology related to pipelines.

    • Pipeline:

      A pipeline is a software delivery process that is broken into different stages and steps. Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. A pipeline is based on a specific repository. It defines the process to build, test, and deploy your code. Rancher uses the pipeline as code model. Pipeline configuration is represented as a pipeline file in the source code repository, using the file name .rancher-pipeline.yml or .rancher-pipeline.yaml.

    • Stages:

      A pipeline stage consists of multiple steps. Stages are executed in the order defined in the pipeline file. The steps in a stage are executed concurrently. A stage starts when all steps in the former stage finish without failure.

    • Steps:

      A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than 0. If a step exits with this failure code, the entire pipeline fails and terminates.

    • Workspace:

      The workspace is the working directory shared by all pipeline steps. In the beginning of a pipeline, source code is checked out to the workspace. The command for every step bootstraps in the workspace. During a pipeline execution, the artifacts from a previous step will be available in future steps. The working directory is an ephemeral volume and will be cleaned out with the executor pod when a pipeline execution is finished.

    Typically, pipeline stages include:

    • Build:

      Each time code is checked into your repository, the pipeline automatically clones the repo and builds a new iteration of your software. Throughout this process, the software is typically reviewed by automated tests.

    • Publish:

      After the build is completed, either a Docker image is built and published to a Docker registry or a catalog template is published.

    • Deploy:

      After the artifacts are published, you would release your application so users could start using the updated product.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/pipelines/configure-persistent-data.html b/reference-guides/pipelines/configure-persistent-data.html index a5e31e99377..0352a4dfae7 100644 --- a/reference-guides/pipelines/configure-persistent-data.html +++ b/reference-guides/pipelines/configure-persistent-data.html @@ -5,13 +5,13 @@ Configuring Persistent Data for Pipeline Components | Rancher Manager - +
    Version: v2.6

    Configuring Persistent Data for Pipeline Components

    The pipelines' internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

    This section assumes that you understand how persistent storage works in Kubernetes. For more information, refer to the section on how storage works.

    Prerequisites for both parts A and B:

    Persistent volumes must be available for the cluster.

    A. Configuring Persistent Data for Docker Registry​

    1. Click ☰ > Cluster Management.

    2. Go to the cluster that you created and click Explore.

    3. Click Workload.

    4. Find the docker-registry workload and select ⋮ > Edit.

    5. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

      • Add Volume > Add a new persistent volume (claim)
      • Add Volume > Use an existing persistent volume (claim)

    6. Complete the form that displays to choose a persistent volume for the internal Docker registry.

      1. Enter a Name for the volume claim.
      2. Select a volume claim Source:
        • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
        • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
      3. From the Customize section, choose the read/write access for the volume.
      4. Click Define.

    7. From the Mount Point field, enter /var/lib/registry, which is the data storage path inside the Docker registry container.

    8. Click Upgrade.

    B. Configuring Persistent Data for Minio​

    1. Click ☰ > Cluster Management.

    2. Go to the cluster that you created and click Explore.

    3. Click Workload.

    4. Go to the minio workload and select ⋮ > Edit.

    5. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

      • Add Volume > Add a new persistent volume (claim)
      • Add Volume > Use an existing persistent volume (claim)

    6. Complete the form that displays to choose a persistent volume for the internal Docker registry.

      1. Enter a Name for the volume claim.
      2. Select a volume claim Source:
        • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
        • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
      3. From the Customize section, choose the read/write access for the volume.
      4. Click Define.

    7. From the Mount Point field, enter /data, which is the data storage path inside the Minio container.

    8. Click Upgrade.

    Result: Persistent storage is configured for your pipeline components.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/pipelines/example-repositories.html b/reference-guides/pipelines/example-repositories.html index f9f2b84ab66..df43e584944 100644 --- a/reference-guides/pipelines/example-repositories.html +++ b/reference-guides/pipelines/example-repositories.html @@ -5,13 +5,13 @@ Example Repositories | Rancher Manager - +
    Version: v2.6

    Example Repositories

    Rancher ships with several example repositories that you can use to familiarize yourself with pipelines. We recommend configuring and testing the example repository that most resembles your environment before using pipelines with your own repositories in a production environment. Use this example repository as a sandbox for repo configuration, build demonstration, etc. Rancher includes example repositories for:

    • Go
    • Maven
    • php
    Prerequisites:

    • The example repositories are only available if you have not configured a version control provider.

    • Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines.

    • Note that pipelines in Kubernetes 1.21+ are no longer supported.

      1. In the upper left corner, click ☰ > Global Settings.
      2. Click Feature Flags.
      3. Go to the legacy feature flag and click ⋮ > Activate.

    To start using these example repositories,

    1. Enable the example repositories
    2. View the example pipeline
    3. Run the example pipeline

    1. Enable the Example Repositories​

    By default, the example pipeline repositories are disabled. Enable one (or more) to test out the pipeline feature and see how it works.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. In the Pipelines tab, click Configure Repositories.

      note

      Example repositories only display if you haven't fetched your own repos.

    6. Click Enable for one of the example repos (e.g., https://github.com/rancher/pipeline-example-go.git). Then click Done.

    Results:

    • The example repository is enabled to work with a pipeline is available in the Pipeline tab.

    • The following workloads are deployed to a new namespace:

      • docker-registry
      • jenkins
      • minio

    2. View the Example Pipeline​

    After enabling an example repository, review the pipeline to see how it is set up.

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.
    5. In the Pipelines tab, click Configure Repositories.
    6. Find the example repository, select ⋮ > Edit Config. There are two ways to view the pipeline:
    • Rancher UI: Click on Edit Config or View/Edit YAML to view the stages and steps of the pipeline. The YAML view shows the ./rancher-pipeline.yml file.

    3. Run the Example Pipeline​

    After enabling an example repository, run the pipeline to see how it works.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. In the Pipelines tab, go to the pipeline and select the vertical ⋮ > Run.

      note

      When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components.

    Result: The pipeline runs. You can see the results in the logs.

    What's Next?​

    For detailed information about setting up your own pipeline for your repository, configure a version control provider, enable a repository and finally configure your pipeline.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/pipelines/example-yaml.html b/reference-guides/pipelines/example-yaml.html index 1423221bdf3..4a44f798bb5 100644 --- a/reference-guides/pipelines/example-yaml.html +++ b/reference-guides/pipelines/example-yaml.html @@ -5,13 +5,13 @@ Example YAML File | Rancher Manager - +
    Version: v2.6

    Example YAML File

    Pipelines can be configured either through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml.

    In the pipeline configuration reference, we provide examples of how to configure each feature using the Rancher UI or using YAML configuration.

    Below is a full example rancher-pipeline.yml for those who want to jump right in.

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${FIRST_KEY} && echo ${ALIAS_ENV}
          # Set environment variables in container for the step
          env:
            FIRST_KEY: VALUE
            SECOND_KEY: VALUE2
          # Set environment variables from project secrets
          envFrom:
          - sourceName: my-secret
            sourceKey: secret-key
            targetKey: ALIAS_ENV
        - runScriptConfig:
            image: busybox
            shellScript: date -R
          # Conditions for steps
          when:
            branch: [ master, dev ]
            event: push
      - name: Publish my image
        steps:
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: rancher/rancher:v2.0.0
            # Optionally push to remote registry
            pushRemote: true
            registry: reg.example.com
      - name: Deploy some workloads
        steps:
        - applyYamlConfig:
            path: ./deployment.yaml
    # branch conditions for the pipeline
    branch:
      include: [ master, feature/*]
      exclude: [ dev ]
    # timeout in minutes
    timeout: 30
    notification:
      recipients:
      - # Recipient
        recipient: "#mychannel"
        # ID of Notifier
        notifier: "c-wdcsr:n-c9pg7"
      - recipient: "test@example.com"
        notifier: "c-wdcsr:n-lkrhd"
      # Select which statuses you want the notification to be sent
      condition: ["Failed", "Success", "Changed"]
      # Ability to override the default message (Optional)
      message: "my-message"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/pipelines/pipeline-configuration.html b/reference-guides/pipelines/pipeline-configuration.html index dbc997a98ca..f0cc166760e 100644 --- a/reference-guides/pipelines/pipeline-configuration.html +++ b/reference-guides/pipelines/pipeline-configuration.html @@ -5,14 +5,14 @@ Pipeline Configuration Reference | Rancher Manager - +
    Version: v2.6

    Pipeline Configuration Reference

    In this section, you'll learn how to configure pipelines.

    Step Types​

    Within each stage, you can add as many steps as you'd like. When there are multiple steps in one stage, they run concurrently.

    Step types include:

    Configuring Steps By UI​

    If you haven't added any stages, click Configure pipeline for this branch to configure the pipeline through the UI.

    1. Add stages to your pipeline execution by clicking Add Stage.

      1. Enter a Name for each stage of your pipeline.
      2. For each stage, you can configure trigger rules by clicking on Show Advanced Options. Note: this can always be updated at a later time.

    2. After you've created a stage, start adding steps by clicking Add a Step. You can add multiple steps to each stage.

    Configuring Steps by YAML​

    For each stage, you can add multiple steps. Read more about each step type and the advanced options to get all the details on how to configure the YAML. This is only a small example of how to have multiple stages with a singular step in each stage.

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
          - runScriptConfig:
              image: busybox
              shellScript: date -R
      - name: Publish my image
        steps:
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: rancher/rancher:v2.0.0
            # Optionally push to remote registry
            pushRemote: true
            registry: reg.example.com

    Step Type: Run Script

    The Run Script step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience, you can use variables to refer to metadata of a pipeline execution. Please refer to the pipeline variable substitution reference for the list of available variables.

    Configuring Script by UI​

    1. From the Step Type drop-down, choose Run Script and fill in the form.

    2. Click Add.

    Configuring Script by YAML​

    # example
    stages:
    - name: Build something
      steps:
      - runScriptConfig:
          image: golang
          shellScript: go build

    Step Type: Build and Publish Images​

    The Build and Publish Image step builds and publishes a Docker image. This process requires a Dockerfile in your source code's repository to complete successfully.

    The option to publish an image to an insecure registry is not exposed in the UI, but you can specify an environment variable in the YAML that allows you to publish an image insecurely.

    Configuring Building and Publishing Images by UI​

    1. From the Step Type drop-down, choose Build and Publish.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      Dockerfile PathThe relative path to the Dockerfile in the source code repo. By default, this path is ./Dockerfile, which assumes the Dockerfile is in the root directory. You can set it to other paths in different use cases (./path/to/myDockerfile for example).
      Image NameThe image name in name:tag format. The registry address is not required. For example, to build example.com/repo/my-image:dev, enter repo/my-image:dev.
      Push image to remote repositoryAn option to set the registry that publishes the image that's built. To use this option, enable it and choose a registry from the drop-down. If this option is disabled, the image is pushed to the internal registry.
      Build Context

      (Show advanced options)      		By default, the root directory of the source code (.). For more details, see the Docker build command documentation.

    Configuring Building and Publishing Images by YAML​

    You can use specific arguments for Docker daemon and the build. They are not exposed in the UI, but they are available in pipeline YAML format, as indicated in the example below. Available environment variables include:

    Variable NameDescription
    PLUGIN_DRY_RUNDisable docker push
    PLUGIN_DEBUGDocker daemon executes in debug mode
    PLUGIN_MIRRORDocker daemon registry mirror
    PLUGIN_INSECUREDocker daemon allows insecure registries
    PLUGIN_BUILD_ARGSDocker build args, a comma separated list

    # This example shows an environment variable being used
    # in the Publish Image step. This variable allows you to
    # publish an image to an insecure registry:

    stages:
    - name: Publish Image
      steps:
      - publishImageConfig:
          dockerfilePath: ./Dockerfile
          buildContext: .
          tag: repo/app:v1
          pushRemote: true
          registry: example.com
        env:
          PLUGIN_INSECURE: "true"

    Step Type: Publish Catalog Template​

    The Publish Catalog Template step publishes a version of a catalog app template (i.e. Helm chart) to a git hosted chart repository. It generates a git commit and pushes it to your chart repository. This process requires a chart folder in your source code's repository and a pre-configured secret in the dedicated pipeline namespace to complete successfully. Any variables in the pipeline variable substitution reference is supported for any file in the chart folder.

    Configuring Publishing a Catalog Template by UI​

    1. From the Step Type drop-down, choose Publish Catalog Template.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      Chart FolderThe relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
      Catalog Template NameThe name of the template. For example, wordpress.
      Catalog Template VersionThe version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
      ProtocolYou can choose to publish via HTTP(S) or SSH protocol.
      SecretThe secret that stores your Git credentials. You need to create a secret in dedicated pipeline namespace in the project before adding this step. If you use HTTP(S) protocol, store Git username and password in USERNAME and PASSWORD key of the secret. If you use SSH protocol, store Git deploy key in DEPLOY_KEY key of the secret. After the secret is created, select it in this option.
      Git URLThe Git URL of the chart repository that the template will be published to.
      Git BranchThe Git branch of the chart repository that the template will be published to.
      Author NameThe author name used in the commit message.
      Author EmailThe author email used in the commit message.

    Configuring Publishing a Catalog Template by YAML​

    You can add Publish Catalog Template steps directly in the .rancher-pipeline.yml file.

    Under the steps section, add a step with publishCatalogConfig. You will provide the following information:

    • Path: The relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
    • CatalogTemplate: The name of the template.
    • Version: The version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
    • GitUrl: The git URL of the chart repository that the template will be published to.
    • GitBranch: The git branch of the chart repository that the template will be published to.
    • GitAuthor: The author name used in the commit message.
    • GitEmail: The author email used in the commit message.
    • Credentials: You should provide Git credentials by referencing secrets in dedicated pipeline namespace. If you publish via SSH protocol, inject your deploy key to the DEPLOY_KEY environment variable. If you publish via HTTP(S) protocol, inject your username and password to USERNAME and PASSWORD environment variables.
    # example
    stages:
    - name: Publish Wordpress Template
      steps:
      - publishCatalogConfig:
          path: ./charts/wordpress/latest
          catalogTemplate: wordpress
          version: ${CICD_GIT_TAG}
          gitUrl: git@github.com:myrepo/charts.git
          gitBranch: master
          gitAuthor: example-user
          gitEmail: user@example.com
        envFrom:
        - sourceName: publish-keys
          sourceKey: DEPLOY_KEY

    Step Type: Deploy YAML​

    This step deploys arbitrary Kubernetes resources to the project. This deployment requires a Kubernetes manifest file to be present in the source code repository. Pipeline variable substitution is supported in the manifest file. You can view an example file at GitHub. Please refer to the pipeline variable substitution reference for the list of available variables.

    Configure Deploying YAML by UI​

    1. From the Step Type drop-down, choose Deploy YAML and fill in the form.

    2. Enter the YAML Path, which is the path to the manifest file in the source code.

    3. Click Add.

    Configure Deploying YAML by YAML​

    # example
    stages:
    - name: Deploy
      steps:
      - applyYamlConfig:
          path: ./deployment.yaml

    Step Type :Deploy Catalog App​

    The Deploy Catalog App step deploys a catalog app in the project. It will install a new app if it is not present, or upgrade an existing one.

    Configure Deploying Catalog App by UI​

    1. From the Step Type drop-down, choose Deploy Catalog App.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      CatalogThe catalog from which the app template will be used.
      Template NameThe name of the app template. For example, wordpress.
      Template VersionThe version of the app template you want to deploy.
      NamespaceThe target namespace where you want to deploy the app.
      App NameThe name of the app you want to deploy.
      AnswersKey-value pairs of answers used to deploy the app.

    Configure Deploying Catalog App by YAML​

    You can add Deploy Catalog App steps directly in the .rancher-pipeline.yml file.

    Under the steps section, add a step with applyAppConfig. You will provide the following information:

    • CatalogTemplate: The ID of the template. This can be found by clicking Launch app and selecting View details for the app. It is the last part of the URL.
    • Version: The version of the template you want to deploy.
    • Answers: Key-value pairs of answers used to deploy the app.
    • Name: The name of the app you want to deploy.
    • TargetNamespace: The target namespace where you want to deploy the app.
    # example
    stages:
    - name: Deploy App
      steps:
      - applyAppConfig:
          catalogTemplate: cattle-global-data:library-mysql
          version: 0.3.8
          answers:
            persistence.enabled: "false"
          name: testmysql
          targetNamespace: test

    Timeouts​

    By default, each pipeline execution has a timeout of 60 minutes. If the pipeline execution cannot complete within its timeout period, the pipeline is aborted.

    Configuring Timeouts by UI​

    Enter a new value in the Timeout field.

    Configuring Timeouts by YAML​

    In the timeout section, enter the timeout value in minutes.

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
    # timeout in minutes
    timeout: 30

    Notifications​

    You can enable notifications to any notifiers based on the build status of a pipeline. Before enabling notifications, Rancher recommends setting up notifiers so it will be easy to add recipients immediately.

    Configuring Notifications by UI​

    1. Within the Notification section, turn on notifications by clicking Enable.

    2. Select the conditions for the notification. You can select to get a notification for the following statuses: Failed, Success, Changed. For example, if you want to receive notifications when an execution fails, select Failed.

    3. If you don't have any existing notifiers, Rancher will provide a warning that no notifiers are set up and provide a link to be able to go to the notifiers page. Follow the instructions to add a notifier. If you already have notifiers, you can add them to the notification by clicking the Add Recipient button.

      note

      Notifiers are configured at a cluster level and require a different level of permissions.

    4. For each recipient, select which notifier type from the dropdown. Based on the type of notifier, you can use the default recipient or override the recipient with a different one. For example, if you have a notifier for Slack, you can update which channel to send the notification to. You can add additional notifiers by clicking Add Recipient.

    Configuring Notifications by YAML​

    In the notification section, you will provide the following information:

    • Recipients: This will be the list of notifiers/recipients that will receive the notification.
      • Notifier: The ID of the notifier. This can be found by finding the notifier and selecting View in API to get the ID.
      • Recipient: Depending on the type of the notifier, the "default recipient" can be used or you can override this with a different recipient. For example, when configuring a slack notifier, you select a channel as your default recipient, but if you wanted to send notifications to a different channel, you can select a different recipient.
    • Condition: Select which conditions of when you want the notification to be sent.
    • Message (Optional): If you want to change the default notification message, you can edit this in the yaml. Note: This option is not available in the UI.
    # Example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
    notification:
      recipients:
      - # Recipient
        recipient: "#mychannel"
        # ID of Notifier
        notifier: "c-wdcsr:n-c9pg7"
      - recipient: "test@example.com"
        notifier: "c-wdcsr:n-lkrhd"
      # Select which statuses you want the notification to be sent
      condition: ["Failed", "Success", "Changed"]
      # Ability to override the default message (Optional)
      message: "my-message"

    Triggers and Trigger Rules​

    After you configure a pipeline, you can trigger it using different methods:

    • Manually:

      After you configure a pipeline, you can trigger a build using the latest CI definition from Rancher UI. When a pipeline execution is triggered, Rancher dynamically provisions a Kubernetes pod to run your CI tasks and then remove it upon completion.

    • Automatically:

      When you enable a repository for a pipeline, webhooks are automatically added to the version control system. When project users interact with the repo by pushing code, opening pull requests, or creating a tag, the version control system sends a webhook to Rancher Server, triggering a pipeline execution.

      To use this automation, webhook management permission is required for the repository. Therefore, when users authenticate and fetch their repositories, only those on which they have webhook management permission will be shown.

    Trigger rules can be created to have fine-grained control of pipeline executions in your pipeline configuration. Trigger rules come in two types:

    • Run this when: This type of rule starts the pipeline, stage, or step when a trigger explicitly occurs.

    • Do Not Run this when: This type of rule skips the pipeline, stage, or step when a trigger explicitly occurs.

    If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a pipeline is skipped, none of the pipeline is executed. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run.

    Wildcard character (*) expansion is supported in branch conditions.

    Configuring Pipeline Triggers​

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    6. Click on Show Advanced Options.

    7. In the Trigger Rules section, configure rules to run or skip the pipeline.

      1. Click Add Rule. In the Value field, enter the name of the branch that triggers the pipeline.

      2. Optional: Add more branches that trigger a build.

    8. Click Done.

    Configuring Stage Triggers​

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    6. Find the stage that you want to manage trigger rules, click the Edit icon for that stage.

    7. Click Show advanced options.

    8. In the Trigger Rules section, configure rules to run or skip the stage.

      1. Click Add Rule.

      2. Choose the Type that triggers the stage and enter a value.

        TypeValue
        BranchThe name of the branch that triggers the stage.
        EventThe type of event that triggers the stage. Values are: Push, Pull Request, Tag

    9. Click Save.

    Configuring Step Triggers​

    1. In the upper left corner, click ☰ > Cluster Management.

    2. Go to the cluster where you want to configure pipelines and click Explore.

    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.

    4. In the left navigation bar, click Legacy > Project > Pipelines.

    5. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    6. Find the step that you want to manage trigger rules, click the Edit icon for that step.

    7. Click Show advanced options.

    8. In the Trigger Rules section, configure rules to run or skip the step.

      1. Click Add Rule.

      2. Choose the Type that triggers the step and enter a value.

        TypeValue
        BranchThe name of the branch that triggers the step.
        EventThe type of event that triggers the step. Values are: Push, Pull Request, Tag

    9. Click Save.

    Configuring Triggers by YAML​

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: date -R
          # Conditions for steps
          when:
            branch: [ master, dev ]
            event: push
    # branch conditions for the pipeline
    branch:
      include: [ master, feature/*]
      exclude: [ dev ]

    Environment Variables​

    When configuring a pipeline, certain step types allow you to use environment variables to configure the step's script.

    Configuring Environment Variables by UI​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.
    5. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.
    6. Within one of the stages, find the step that you want to add an environment variable for, click the Edit icon.
    7. Click Show advanced options.
    8. Click Add Variable, and then enter a key and value in the fields that appear. Add more variables if needed.
    9. Add your environment variable(s) into either the script or file.
    10. Click Save.

    Configuring Environment Variables by YAML​

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY}
          env:
            FIRST_KEY: VALUE
            SECOND_KEY: VALUE2

    Secrets​

    If you need to use security-sensitive information in your pipeline scripts (like a password), you can pass them in using Kubernetes secrets.

    Prerequisite​

    Create a secret in the same project as your pipeline, or explicitly in the namespace where pipeline build pods run.


    note

    Secret injection is disabled on pull request events.

    Configuring Secrets by UI​

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.
    5. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.
    6. Within one of the stages, find the step that you want to use a secret for, click the Edit icon.
    7. Click Show advanced options.
    8. Click Add From Secret. Select the secret file that you want to use. Then choose a key. Optionally, you can enter an alias for the key.
    9. Click Save.

    Configuring Secrets by YAML​

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${ALIAS_ENV}
          # environment variables from project secrets
          envFrom:
          - sourceName: my-secret
            sourceKey: secret-key
            targetKey: ALIAS_ENV

    Pipeline Variable Substitution Reference​

    For your convenience, the following variables are available for your pipeline configuration scripts. During pipeline executions, these variables are replaced by metadata. You can reference them in the form of ${VAR_NAME}.

    Variable NameDescription
    CICD_GIT_REPO_NAMERepository name (Github organization omitted).
    CICD_GIT_URLURL of the Git repository.
    CICD_GIT_COMMITGit commit ID being executed.
    CICD_GIT_BRANCHGit branch of this event.
    CICD_GIT_REFGit reference specification of this event.
    CICD_GIT_TAGGit tag name, set on tag event.
    CICD_EVENTEvent that triggered the build (push, pull_request or tag).
    CICD_PIPELINE_IDRancher ID for the pipeline.
    CICD_EXECUTION_SEQUENCEBuild number of the pipeline.
    CICD_EXECUTION_IDCombination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}.
    CICD_REGISTRYAddress for the Docker registry for the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step.
    CICD_IMAGEName of the image built from the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step. It does not contain the image tag.

    Example

    Global Pipeline Execution Settings​

    After configuring a version control provider, there are several options that can be configured globally on how pipelines are executed in Rancher.

    Changing Pipeline Settings​

    Prerequisite:

    Because the pipelines app was deprecated in favor of Fleet, you will need to turn on the feature flag for legacy features before using pipelines. Note that pipelines in Kubernetes 1.21+ are no longer supported.

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags.
    3. Go to the legacy feature flag and click ⋮ > Activate.

    To edit these settings:

    1. In the upper left corner, click ☰ > Cluster Management.
    2. Go to the cluster where you want to configure pipelines and click Explore.
    3. In the dropdown menu in the top navigation bar, select the project where you want to configure pipelines.
    4. In the left navigation bar, click Legacy > Project > Pipelines.

    Executor Quota​

    Select the maximum number of pipeline executors. The executor quota decides how many builds can run simultaneously in the project. If the number of triggered builds exceeds the quota, subsequent builds will queue until a vacancy opens. By default, the quota is 2. A value of 0 or less removes the quota limit.

    Resource Quota for Executors​

    Configure compute resources for Jenkins agent containers. When a pipeline execution is triggered, a build pod is dynamically provisioned to run your CI tasks. Under the hood, A build pod consists of one Jenkins agent container and one container for each pipeline step. You can manage compute resources for every containers in the pod.

    Edit the Memory Reservation, Memory Limit, CPU Reservation or CPU Limit, then click Update Limit and Reservation.

    To configure compute resources for pipeline-step containers:

    You can configure compute resources for pipeline-step containers in the .rancher-pipeline.yml file.

    In a step, you will provide the following information:

    • CPU Reservation (CpuRequest): CPU request for the container of a pipeline step.
    • CPU Limit (CpuLimit): CPU limit for the container of a pipeline step.
    • Memory Reservation (MemoryRequest): Memory request for the container of a pipeline step.
    • Memory Limit (MemoryLimit): Memory limit for the container of a pipeline step.
    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
          cpuRequest: 100m
          cpuLimit: 1
          memoryRequest:100Mi
          memoryLimit: 1Gi
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: repo/app:v1
          cpuRequest: 100m
          cpuLimit: 1
          memoryRequest:100Mi
          memoryLimit: 1Gi
    note

    Rancher sets default compute resources for pipeline steps except for Build and Publish Images and Run Script steps. You can override the default value by specifying compute resources in the same way.

    Custom CA​

    If you want to use a version control provider with a certificate from a custom/internal CA root, the CA root certificates need to be added as part of the version control provider configuration in order for the pipeline build pods to succeed.

    1. Click Edit cacerts.

    2. Paste in the CA root certificates and click Save cacerts.

    Result: Pipelines can be used and new pods will be able to work with the self-signed-certificate.

    Persistent Data for Pipeline Components

    The internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

    For details on setting up persistent storage for pipelines, refer to this page.

    Example rancher-pipeline.yml​

    An example pipeline configuration file is on this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/prometheus-federator/rbac.html b/reference-guides/prometheus-federator/rbac.html index 2d4294db3fb..c794e0227a5 100644 --- a/reference-guides/prometheus-federator/rbac.html +++ b/reference-guides/prometheus-federator/rbac.html @@ -5,13 +5,13 @@ Role-Based Access Control | Rancher Manager - +
    Version: v2.6

    Role-Based Access Control

    This section describes the expectations for Role-Based Access Control (RBAC) for Prometheus Federator.

    As described in the section on namespaces, Prometheus Federator expects that Project Owners, Project Members, and other users in the cluster with Project-level permissions (e.g. permissions in a certain set of namespaces identified by a single label selector) have minimal permissions in any namespaces except the Project Registration Namespace (which is imported into the project by default) and those that already comprise their projects. Therefore, in order to allow Project Owners to assign specific chart permissions to other users in their Project namespaces, the Helm Project Operator will automatically watch the following bindings:

    • ClusterRoleBindings
    • RoleBindings in the Project Release Namespace

    On observing a change to one of those types of bindings, the Helm Project Operator will check whether the roleRef that the the binding points to matches a ClusterRole with the name provided under:

    • helmProjectOperator.releaseRoleBindings.clusterRoleRefs.admin
    • helmProjectOperator.releaseRoleBindings.clusterRoleRefs.edit
    • helmProjectOperator.releaseRoleBindings.clusterRoleRefs.view

    By default, these roleRefs will correspond to admin, edit, and view respectively, which are the default Kubernetes user-facing roles.

    note

    For Rancher RBAC users, these default Kubernetes user-facing roles directly correlate to the Project Owner, Project Member, and Read-Only default Project Role Templates.

    If the roleRef matches, the Helm Project Operator will filter the subjects of the binding for all Users and Groups and use that to automatically construct a RoleBinding for each Role in the Project Release Namespace with the same name as the role and the following labels:

    • helm.cattle.io/project-helm-chart-role: {{ .Release.Name }}
    • helm.cattle.io/project-helm-chart-role-aggregate-from: <admin|edit|view>

    By default, rancher-project-monitoring, the underlying chart deployed by Prometheus Federator, creates three default Roles per Project Release Namespace that provide admin, edit, and view users to permissions to view the Prometheus, Alertmanager, and Grafana UIs of the Project Monitoring Stack to provide least privilege. However, if a Cluster Admin would like to assign additional permissions to certain users, they can either directly assign RoleBindings in the Project Release Namespace to certain users or create Roles with the above two labels on them to allow Project Owners to control assigning those RBAC roles to users in their Project Registration namespaces.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-cluster-tools.html b/reference-guides/rancher-cluster-tools.html index 365489034b0..124fb545659 100644 --- a/reference-guides/rancher-cluster-tools.html +++ b/reference-guides/rancher-cluster-tools.html @@ -5,13 +5,13 @@ Cluster Tools for Logging, Monitoring, and Visibility | Rancher Manager - +
    Version: v2.6

    Cluster Tools for Logging, Monitoring, and Visibility

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories:

    Logging​

    Logging is helpful because it allows you to:

    • Capture and analyze the state of your cluster
    • Look for trends in your environment
    • Save your logs to a safe location outside of your cluster
    • Stay informed of events like a container crashing, a pod eviction, or a node dying
    • More easily debugg and troubleshoot problems

    Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

    For more information, refer to the logging documentation here.

    Monitoring and Alerts​

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.

    After monitoring is enabled, you can set up alerts and notifiers that provide the mechanism to receive them.

    Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

    Alerts are rules that trigger those notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

    For more information, refer to the monitoring documentation here.

    Istio​

    Istio is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.

    Rancher's integration with Istio was improved in Rancher v2.5.

    For more information, refer to the Istio documentation here.

    OPA Gatekeeper​

    OPA Gatekeeper is an open-source project that provides integration between OPA and Kubernetes to provide policy control via admission controller webhooks. For details on how to enable Gatekeeper in Rancher, refer to the OPA Gatekeeper section.

    CIS Scans​

    Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.

    For more information, refer to the CIS scan documentation here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-manager-architecture/architecture-recommendations.html b/reference-guides/rancher-manager-architecture/architecture-recommendations.html index 6ce1ed138bb..0b9be8861fa 100644 --- a/reference-guides/rancher-manager-architecture/architecture-recommendations.html +++ b/reference-guides/rancher-manager-architecture/architecture-recommendations.html @@ -5,13 +5,13 @@ Architecture Recommendations | Rancher Manager - +
    Version: v2.6

    Architecture Recommendations

    If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the node running Rancher should be separate from downstream clusters.

    Separation of Rancher and User Clusters

    A user cluster is a downstream Kubernetes cluster that runs your apps and services.

    If you have a Docker installation of Rancher, the node running the Rancher server should be separate from your downstream clusters.

    If Rancher is intended to manage downstream Kubernetes clusters, the Kubernetes cluster that the Rancher server runs on should also be separate from the downstream user clusters.

    Separation of Rancher Server from User Clusters

    Why HA is Better for Rancher in Production

    We recommend installing the Rancher server on a high-availability Kubernetes cluster, primarily because it protects the Rancher server data. In a high-availability installation, a load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure.

    We don't recommend installing Rancher in a single Docker container, because if the node goes down, there is no copy of the cluster data available on other nodes and you could lose the data on your Rancher server.

    K3s Kubernetes Cluster Installations​

    One option for the underlying Kubernetes cluster is to use K3s Kubernetes. K3s is Rancher's CNCF certified Kubernetes distribution. It is easy to install and uses half the memory of Kubernetes, all in a binary of less than 100 MB. Another advantage of K3s is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.

    Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

    Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

    RKE Kubernetes Cluster Installations​

    In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.

    Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server

    Architecture of an RKE Kubernetes cluster running the Rancher management server

    Recommended Load Balancer Configuration for Kubernetes Installations

    We recommend the following configurations for the load balancer and Ingress controllers:

    • The DNS for Rancher should resolve to a Layer 4 load balancer (TCP).
    • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
    • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
    • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
    Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at Ingress controllers

    Rancher HA

    Environment for Kubernetes Installations

    It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine.

    For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    Recommended Node Roles for Kubernetes Installations

    The below recommendations apply when Rancher is installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.

    K3s Cluster Roles​

    In K3s clusters, there are two types of nodes: server nodes and agent nodes. Both servers and agents can have workloads scheduled on them. Server nodes run the Kubernetes master.

    For the cluster running the Rancher management server, we recommend using two server nodes. Agent nodes are not required.

    RKE Cluster Roles​

    If Rancher is installed on an RKE Kubernetes cluster, the cluster should have three nodes, and each node should have all three Kubernetes roles: etcd, controlplane, and worker.

    Contrasting RKE Cluster Architecture for Rancher Server and for Downstream Kubernetes Clusters​

    Our recommendation for RKE node roles on the Rancher server cluster contrasts with our recommendations for the downstream user clusters that run your apps and services.

    Rancher uses RKE as a library when provisioning downstream Kubernetes clusters. Note: The capability to provision downstream K3s clusters will be added in a future version of Rancher.

    For downstream Kubernetes clusters, we recommend that each node in a user cluster should have a single role for stability and scalability.

    Kubernetes Roles for Nodes in Rancher Server Cluster vs. User Clusters

    RKE only requires at least one node with each role and does not require nodes to be restricted to one role. However, for the clusters that run your apps, we recommend separate roles for each node so that workloads on worker nodes don't interfere with the Kubernetes master or cluster data as your services scale.

    We recommend that downstream user clusters should have at least:

    • Three nodes with only the etcd role to maintain a quorum if one node is lost, making the state of your cluster highly available
    • Two nodes with only the controlplane role to make the master component highly available
    • One or more nodes with only the worker role to run the Kubernetes node components, as well as the workloads for your apps and services

    With that said, it is safe to use all three roles on three nodes when setting up the Rancher server because:

    • It allows one etcd node failure.
    • It maintains multiple instances of the master components by having multiple controlplane nodes.
    • No other workloads than Rancher itself should be created on this cluster.

    Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of downstream clusters.

    For more best practices for downstream clusters, refer to the production checklist or our best practices guide.

    Architecture for an Authorized Cluster Endpoint (ACE)

    If you are using an authorized cluster endpoint (ACE), we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the controlplane role.

    If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate, which will be included in the generated kubeconfig file to validate the certificate chain. See the documentation on kubeconfig files and API keys for more information.

    As of Rancher v2.6.3, ACE support is available for registered RKE2 and K3s clusters. To view the manual steps to perform on the downstream cluster to enable the ACE, click here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html b/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html index f5c9e70fda3..d1c7da78083 100644 --- a/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html +++ b/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html @@ -5,14 +5,14 @@ Communicating with Downstream User Clusters | Rancher Manager - +
    Version: v2.6

    Communicating with Downstream User Clusters

    This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services.

    The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters.

    Communicating with Downstream Clusters

    Rancher Components

    The following descriptions correspond to the numbers in the diagram above:

    1. The Authentication Proxy
    2. Cluster Controllers and Cluster Agents
    3. Node Agents
    4. Authorized Cluster Endpoint

    1. The Authentication Proxy​

    In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a kubectl command to see the pods. Bob is authenticated through Rancher's authentication proxy.

    The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.

    Rancher communicates with Kubernetes clusters using a service account, which provides an identity for processes that run in a pod.

    By default, Rancher generates a kubeconfig file that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (kube_config_rancher-cluster.yml) contains full access to the cluster.

    2. Cluster Controllers and Cluster Agents​

    Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server.

    There is one cluster controller and one cluster agent for each downstream cluster. Each cluster controller:

    • Watches for resource changes in the downstream cluster
    • Brings the current state of the downstream cluster to the desired state
    • Configures access control policies to clusters and projects
    • Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE

    By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a node agent instead.

    The cluster agent, also called cattle-cluster-agent, is a component that runs in a downstream user cluster. It performs the following tasks:

    • Connects to the Kubernetes API of Rancher-launched Kubernetes clusters
    • Manages workloads, pod creation and deployment within each cluster
    • Applies the roles and bindings defined in each cluster's global policies
    • Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health

    3. Node Agents​

    If the cluster agent (also called cattle-cluster-agent) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.

    The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.

    4. Authorized Cluster Endpoint​

    An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy.

    The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher used RKE to provision the cluster. It is not available for imported clusters, or for clusters in a hosted Kubernetes provider, such as Amazon's EKS.

    There are two main reasons why a user might need the authorized cluster endpoint:

    • To access a downstream user cluster while Rancher is down
    • To reduce latency in situations where the Rancher server and downstream cluster are separated by a long distance

    The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

    Like the authorized cluster endpoint, the kube-api-auth authentication service is also only available for Rancher-launched Kubernetes clusters.

    Example scenario: Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint.

    With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for kubectl and helm.

    You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the section on accessing your cluster with kubectl and the kubeconfig file.

    Important Files

    The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down.
    • rancher-cluster.rkestate: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the kubeconfig file documentation.

    Tools for Provisioning Kubernetes Clusters

    The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.

    Rancher Launched Kubernetes for Nodes Hosted in an Infrastructure Provider​

    Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

    Rancher provisions this type of cluster using RKE and docker-machine.

    Rancher Launched Kubernetes for Custom Nodes​

    When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster.

    Rancher provisions this type of cluster using RKE.

    Hosted Kubernetes Providers​

    When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    Rancher provisions this type of cluster using kontainer-engine.

    Imported Kubernetes Clusters​

    In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

    Rancher Server Components and Source Code

    This diagram shows each component that the Rancher server is composed of:

    Rancher Components

    The GitHub repositories for Rancher can be found at the following links:

    This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on contributing to Rancher. To see all libraries and projects used in Rancher, see the go.mod file in the rancher/rancher repository.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-manager-architecture/rancher-server-and-components.html b/reference-guides/rancher-manager-architecture/rancher-server-and-components.html index ba14d9e4211..0a735d8d4f2 100644 --- a/reference-guides/rancher-manager-architecture/rancher-server-and-components.html +++ b/reference-guides/rancher-manager-architecture/rancher-server-and-components.html @@ -5,13 +5,13 @@ Rancher Server and Components | Rancher Manager - +
    Version: v2.6

    Rancher Server and Components

    The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment.

    The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service).

    For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    The diagram below shows how users can manipulate both Rancher-launched Kubernetes clusters and hosted Kubernetes clusters through Rancher's authentication proxy:

    Managing Kubernetes Clusters through Rancher's Authentication Proxy

    Architecture

    You can install Rancher on a single node, or on a high-availability Kubernetes cluster.

    A high-availability Kubernetes installation is recommended for production.

    A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version.

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-project-tools.html b/reference-guides/rancher-project-tools.html index 8f4f4d9b257..d0c9530de85 100644 --- a/reference-guides/rancher-project-tools.html +++ b/reference-guides/rancher-project-tools.html @@ -5,13 +5,13 @@ Project Tools for Logging, Monitoring, and Visibility | Rancher Manager - +
    Version: v2.6

    Project Tools for Logging, Monitoring, and Visibility

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

    Notifiers and Alerts​

    Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Before they can be enabled, the monitoring application must be installed.

    Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

    Alerts are rules that trigger those notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

    Logging​

    Logging is helpful because it allows you to:

    • Capture and analyze the state of your cluster
    • Look for trends in your environment
    • Save your logs to a safe location outside of your cluster
    • Stay informed of events like a container crashing, a pod eviction, or a node dying
    • More easily debugg and troubleshoot problems

    Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

    For details, refer to the logging section.

    Monitoring​

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. For details, refer to the monitoring section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/kubernetes-security-best-practices.html b/reference-guides/rancher-security/kubernetes-security-best-practices.html index da557990e62..fb585c84708 100644 --- a/reference-guides/rancher-security/kubernetes-security-best-practices.html +++ b/reference-guides/rancher-security/kubernetes-security-best-practices.html @@ -5,13 +5,13 @@ Kubernetes Security Best Practices | Rancher Manager - +
    Version: v2.6

    Kubernetes Security Best Practices

    Restricting cloud metadata API access​

    Cloud providers such as AWS, Azure, DigitalOcean or GCP often expose metadata services locally to instances. By default, this endpoint is accessible by pods running on a cloud instance, including pods in hosted Kubernetes providers such as EKS, AKS, DigitalOcean Kubernetes or GKE, and can contain cloud credentials for that node, provisioning data such as kubelet credentials, or other sensitive data. To mitigate this risk when running on a cloud platform, follow the Kubernetes security recommendations: limit permissions given to instance credentials, use network policies to restrict pod access to the metadata API, and avoid using provisioning data to deliver secrets.

    It is advised to consult your cloud provider's security best practices for further recommendations and specific details on how to restrict access to cloud instance metadata API.

    Further references: MITRE ATT&CK knowledge base on - Unsecured Credentials: Cloud Instance Metadata API.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-hardening-guide-with-cis-v1.6-benchmark.html b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-hardening-guide-with-cis-v1.6-benchmark.html index cc5d8ada7a3..76c779fb7a5 100644 --- a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-hardening-guide-with-cis-v1.6-benchmark.html +++ b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-hardening-guide-with-cis-v1.6-benchmark.html @@ -5,13 +5,13 @@ RKE Hardening Guide with CIS v1.6 Benchmark | Rancher Manager - +
    Version: v2.6

    RKE Hardening Guide with CIS v1.6 Benchmark

    This document provides prescriptive guidance for hardening a production installation of a RKE cluster to be used with Rancher v2.6. It outlines the configurations and controls required to address Kubernetes benchmark controls from the Center for Information Security (CIS).

    note

    This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes.

    This hardening guide is intended to be used for RKE clusters and associated with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

    Rancher VersionCIS Benchmark VersionKubernetes Version
    Rancher v2.6Benchmark v1.6Kubernetes v1.18 up to v1.23

    Click here to download a PDF version of this document.

    Overview​

    This document provides prescriptive guidance for hardening a RKE cluster to be used for installing Rancher v2.6 with Kubernetes v1.18 up to v1.23 or provisioning a RKE cluster with Kubernetes v1.18 up to v1.23 to be used within Rancher v2.6. It outlines the configurations required to address Kubernetes benchmark controls from the Center for Information Security (CIS).

    For more details about evaluating a hardened cluster against the official CIS benchmark, refer to the CIS 1.6 Benchmark - Self-Assessment Guide - Rancher v2.6.

    Known Issues​

    • Rancher exec shell and view logs for pods are not functional in a CIS v1.6 hardened setup when only public IP is provided when registering custom nodes. This functionality requires a private IP to be provided when registering the custom nodes.
    • When setting the default_pod_security_policy_template_id: to restricted or restricted-noroot, based on the pod security policies (PSP) provided by Rancher, Rancher creates RoleBindings and ClusterRoleBindings on the default service accounts. The CIS v1.6 check 5.1.5 requires that the default service accounts have no roles or cluster roles bound to it apart from the defaults. In addition the default service accounts should be configured such that it does not provide a service account token and does not have any explicit rights assignments.

    Configure Kernel Runtime Parameters​

    The following sysctl configuration is recommended for all nodes type in the cluster. Set the following parameters in /etc/sysctl.d/90-kubelet.conf:

    vm.overcommit_memory=1
    vm.panic_on_oom=0
    kernel.panic=10
    kernel.panic_on_oops=1
    kernel.keys.root_maxbytes=25000000

    Run sysctl -p /etc/sysctl.d/90-kubelet.conf to enable the settings.

    Configure etcd user and group​

    A user account and group for the etcd service is required to be setup before installing RKE. The uid and gid for the etcd user will be used in the RKE config.yml to set the proper permissions for files and directories during installation time.

    Create etcd user and group​

    To create the etcd user and group run the following console commands. The commands below use 52034 for uid and gid are for example purposes. Any valid unused uid or gid could also be used in lieu of 52034.

    groupadd --gid 52034 etcd
    useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd --shell /usr/sbin/nologin

    Update the RKE config.yml with the uid and gid of the etcd user:

    services:
      etcd:
        gid: 52034
        uid: 52034

    Configure default Service Account​

    Set automountServiceAccountToken to false for default service accounts​

    Kubernetes provides a default service account which is used by cluster workloads where no specific service account is assigned to the pod. Where access to the Kubernetes API from a pod is required, a specific service account should be created for that pod, and rights granted to that service account. The default service account should be configured such that it does not provide a service account token and does not have any explicit rights assignments.

    For each namespace including default and kube-system on a standard RKE install, the default service account must include this value:

    automountServiceAccountToken: false

    Save the following configuration to a file called account_update.yaml.

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: default
    automountServiceAccountToken: false

    Create a bash script file called account_update.sh. Be sure to chmod +x account_update.sh so the script has execute permissions.

    #!/bin/bash -e

    for namespace in $(kubectl get namespaces -A -o=jsonpath="{.items[*]['metadata.name']}"); do
      kubectl patch serviceaccount default -n ${namespace} -p "$(cat account_update.yaml)"
    done

    Configure Network Policy​

    Ensure that all Namespaces have Network Policies defined​

    Running different applications on the same Kubernetes cluster creates a risk of one compromised application attacking a neighboring application. Network segmentation is important to ensure that containers can communicate only with those they are supposed to. A network policy is a specification of how selections of pods are allowed to communicate with each other and other network endpoints.

    Network Policies are namespace scoped. When a network policy is introduced to a given namespace, all traffic not allowed by the policy is denied. However, if there are no network policies in a namespace all traffic will be allowed into and out of the pods in that namespace. To enforce network policies, a CNI (container network interface) plugin must be enabled. This guide uses Canal to provide the policy enforcement. Additional information about CNI providers can be found here.

    Once a CNI provider is enabled on a cluster a default network policy can be applied. For reference purposes a permissive example is provided below. If you want to allow all traffic to all pods in a namespace (even if policies are added that cause some pods to be treated as “isolated”), you can create a policy that explicitly allows all traffic in that namespace. Save the following configuration as default-allow-all.yaml. Additional documentation about network policies can be found on the Kubernetes site.

    note

    This NetworkPolicy is just an example and is not recommended for production use.

    ---
    apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: default-allow-all
    spec:
      podSelector: {}
      ingress:
      - {}
      egress:
      - {}
      policyTypes:
      - Ingress
      - Egress

    Create a bash script file called apply_networkPolicy_to_all_ns.sh. Be sure to chmod +x apply_networkPolicy_to_all_ns.sh so the script has execute permissions.

    #!/bin/bash -e

    for namespace in $(kubectl get namespaces -A -o=jsonpath="{.items[*]['metadata.name']}"); do
      kubectl apply -f default-allow-all.yaml -n ${namespace}
    done

    Execute this script to apply the default-allow-all.yaml configuration with the permissive NetworkPolicy to all namespaces.

    Reference Hardened RKE cluster.yml Configuration​

    The reference cluster.yml is used by the RKE CLI that provides the configuration needed to achieve a hardened install of Rancher Kubernetes Engine (RKE). RKE install documentation is provided with additional details about the configuration items. This reference cluster.yml does not include the required nodes directive which will vary depending on your environment. Documentation for node configuration in RKE can be found here.

    Important:

    For a Kubernetes v1.18 cluster, the configuration spec.volumes: 'ephemeral' should be removed from the PodSecurityPolicy, since it's not supported in this Kubernetes release.

    # If you intend to deploy Kubernetes in an air-gapped environment,
    # please consult the documentation on how to configure custom RKE images.
    # https://rancher.com/docs/rke/latest/en/installation/ .

    # The nodes directive is required and will vary depending on your environment.
    # Documentation for node configuration can be found here:
    # https://rancher.com/docs/rke/latest/en/config-options/nodes/
    nodes: []
    services:
      etcd:
        image: ""
        extra_args: {}
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
        external_urls: []
        ca_cert: ""
        cert: ""
        key: ""
        path: ""
        uid: 52034
        gid: 52034
        snapshot: false
        retention: ""
        creation: ""
        backup_config: null
      kube-api:
        image: ""
        extra_args: {}
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
        service_cluster_ip_range: ""
        service_node_port_range: ""
        pod_security_policy: true
        always_pull_images: false
        secrets_encryption_config:
          enabled: true
          custom_config: null
        audit_log:
          enabled: true
          configuration: null
        admission_configuration: null
        event_rate_limit:
          enabled: true
          configuration: null
      kube-controller:
        image: ""
        extra_args:
          feature-gates: RotateKubeletServerCertificate=true
          tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          bind-address: 127.0.0.1
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
        cluster_cidr: ""
        service_cluster_ip_range: ""
      scheduler:
        image: ""
        extra_args:
          tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          bind-address: 127.0.0.1
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
      kubelet:
        image: ""
        extra_args:
          feature-gates: RotateKubeletServerCertificate=true
          protect-kernel-defaults: true
          tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
        cluster_domain: cluster.local
        infra_container_image: ""
        cluster_dns_server: ""
        fail_swap_on: false
        generate_serving_certificate: true
      kubeproxy:
        image: ""
        extra_args: {}
        extra_binds: []
        extra_env: []
        win_extra_args: {}
        win_extra_binds: []
        win_extra_env: []
    network:
      plugin: ""
      options: {}
      mtu: 0
      node_selector: {}
      update_strategy: null
    authentication:
      strategy: ""
      sans: []
      webhook: null
    addons: |
      # Upstream Kubernetes restricted PSP policy
      # https://github.com/kubernetes/website/blob/564baf15c102412522e9c8fc6ef2b5ff5b6e766c/content/en/examples/policy/restricted-psp.yaml
      apiVersion: policy/v1beta1
      kind: PodSecurityPolicy
      metadata:
        name: restricted-noroot
      spec:
        privileged: false
        # Required to prevent escalations to root.
        allowPrivilegeEscalation: false
        requiredDropCapabilities:
          - ALL
        # Allow core volume types.
        volumes:
          - 'configMap'
          - 'emptyDir'
          - 'projected'
          - 'secret'
          - 'downwardAPI'
          # Assume that ephemeral CSI drivers & persistentVolumes set up by the cluster admin are safe to use.
          - 'csi'
          - 'persistentVolumeClaim'
          - 'ephemeral'
        hostNetwork: false
        hostIPC: false
        hostPID: false
        runAsUser:
          # Require the container to run without root privileges.
          rule: 'MustRunAsNonRoot'
        seLinux:
          # This policy assumes the nodes are using AppArmor rather than SELinux.
          rule: 'RunAsAny'
        supplementalGroups:
          rule: 'MustRunAs'
          ranges:
            # Forbid adding the root group.
            - min: 1
              max: 65535
        fsGroup:
          rule: 'MustRunAs'
          ranges:
            # Forbid adding the root group.
            - min: 1
              max: 65535
        readOnlyRootFilesystem: false
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: psp:restricted-noroot
      rules:
      - apiGroups:
        - extensions
        resourceNames:
        - restricted-noroot
        resources:
        - podsecuritypolicies
        verbs:
        - use
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: psp:restricted-noroot
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: psp:restricted-noroot
      subjects:
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:serviceaccounts
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:authenticated
      ---
      apiVersion: networking.k8s.io/v1
      kind: NetworkPolicy
      metadata:
        name: default-allow-all
      spec:
        podSelector: {}
        ingress:
        - {}
        egress:
        - {}
        policyTypes:
        - Ingress
        - Egress
      ---
      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: default
      automountServiceAccountToken: false
    addons_include: []
    system_images:
      etcd: ""
      alpine: ""
      nginx_proxy: ""
      cert_downloader: ""
      kubernetes_services_sidecar: ""
      kubedns: ""
      dnsmasq: ""
      kubedns_sidecar: ""
      kubedns_autoscaler: ""
      coredns: ""
      coredns_autoscaler: ""
      nodelocal: ""
      kubernetes: ""
      flannel: ""
      flannel_cni: ""
      calico_node: ""
      calico_cni: ""
      calico_controllers: ""
      calico_ctl: ""
      calico_flexvol: ""
      canal_node: ""
      canal_cni: ""
      canal_controllers: ""
      canal_flannel: ""
      canal_flexvol: ""
      weave_node: ""
      weave_cni: ""
      pod_infra_container: ""
      ingress: ""
      ingress_backend: ""
      metrics_server: ""
      windows_pod_infra_container: ""
    ssh_key_path: ""
    ssh_cert_path: ""
    ssh_agent_auth: false
    authorization:
      mode: ""
      options: {}
    ignore_docker_version: false
    kubernetes_version: ""
    private_registries: []
    ingress:
      provider: ""
      options: {}
      node_selector: {}
      extra_args: {}
      dns_policy: ""
      extra_envs: []
      extra_volumes: []
      extra_volume_mounts: []
      update_strategy: null
      http_port: 0
      https_port: 0
      network_mode: ""
    cluster_name:
    cloud_provider:
      name: ""
    prefix_path: ""
    win_prefix_path: ""
    addon_job_timeout: 0
    bastion_host:
      address: ""
      port: ""
      user: ""
      ssh_key: ""
      ssh_key_path: ""
      ssh_cert: ""
      ssh_cert_path: ""
    monitoring:
      provider: ""
      options: {}
      node_selector: {}
      update_strategy: null
      replicas: null
    restore:
      restore: false
      snapshot_name: ""
    dns: null
    upgrade_strategy:
      max_unavailable_worker: ""
      max_unavailable_controlplane: ""
      drain: null
      node_drain_input: null

    Reference Hardened RKE Template Configuration​

    The reference RKE template provides the configuration needed to achieve a hardened install of Kubernetes. RKE templates are used to provision Kubernetes and define Rancher settings. Follow the Rancher documentation for additional installation and RKE template details.

    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted-noroot
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: true
    local_cluster_auth_endpoint:
      enabled: true
    name: ''
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 45
      authentication:
        strategy: x509
      dns:
        nodelocal:
          ip_address: ''
          node_selector: null
          update_strategy: {}
      enable_cri_dockerd: false
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        default_backend: false
        default_ingress_class: true
        http_port: 0
        https_port: 0
        provider: nginx
      kubernetes_version: v1.21.8-rancher1-1
      monitoring:
        provider: metrics-server
        replicas: 1
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        mtu: 0
        options:
          flannel_backend_type: vxlan
        plugin: canal
      rotate_encryption_key: false
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        scheduler:
          extra_args:
            tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          bind-address: 127.0.0.1
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
            timeout: 300
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          retention: 72h
          snapshot: false
          uid: 52034
          gid: 52034
        kube_api:
          always_pull_images: false
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube-controller:
          extra_args:
            feature-gates: RotateKubeletServerCertificate=true
            tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          bind-address: 127.0.0.1
        kubelet:
          extra_args:
            feature-gates: RotateKubeletServerCertificate=true
            protect-kernel-defaults: true
            tls-cipher-suites: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          fail_swap_on: false
          generate_serving_certificate: true
      ssh_agent_auth: false
      upgrade_strategy:
        max_unavailable_controlplane: '1'
        max_unavailable_worker: 10%
    windows_prefered_cluster: false

    Reference Hardened cloud-config Configuration​

    A cloud-config configuration file is generally used in cloud infrastructure environments to allow for configuration management of compute instances. The reference config configures SUSE Linux Enterprise Server (SLES), openSUSE Leap, Red Hat Enterprise Linux (RHEL) and Ubuntu operating system level settings needed before installing Kubernetes.

    Reference Hardened cloud-config for SUSE Linux Enterprise Server 15 (SLES 15) and openSUSE Leap 15​

    #cloud-config
    system_info:
      default_user:
        groups:
        - docker
    write_files:
    - path: "/etc/sysctl.d/90-kubelet.conf"
      owner: root:root
      permissions: '0644'
      content: |
        vm.overcommit_memory=1
        vm.panic_on_oom=0
        kernel.panic=10
        kernel.panic_on_oops=1
        kernel.keys.root_maxbytes=25000000
    package_update: true
    ssh_pwauth: false
    runcmd:
    # Docker should already be installed in SLES 15 SP3
    - zypper install docker containerd
    - systemctl daemon-reload
    - systemctl enable docker.service
    - systemctl start --no-block docker.service
    - sysctl -p /etc/sysctl.d/90-kubelet.conf
    - groupadd --gid 52034 etcd
    - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd --shell /usr/sbin/nologin

    Reference Hardened cloud-config for Red Hat Enterprise Linux 8 (RHEL 8) and Ubuntu 20.04 LTS​

    #cloud-config
    system_info:
      default_user:
        groups:
        - docker
    write_files:
    - path: "/etc/sysctl.d/90-kubelet.conf"
      owner: root:root
      permissions: '0644'
      content: |
        vm.overcommit_memory=1
        vm.panic_on_oom=0
        kernel.panic=10
        kernel.panic_on_oops=1
        kernel.keys.root_maxbytes=25000000
    package_update: true
    ssh_pwauth: false
    runcmd:
    # Install Docker from Rancher's Docker installation scripts - github.com/rancher/install-docker
    - curl https://releases.rancher.com/install-docker/20.10.sh | sh
    - sysctl -p /etc/sysctl.d/90-kubelet.conf
    - groupadd --gid 52034 etcd
    - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd --shell /usr/sbin/nologin
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-self-assessment-guide-with-cis-v1.6-benchmark.html b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-self-assessment-guide-with-cis-v1.6-benchmark.html index 73f33bce730..4bb5f939742 100644 --- a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-self-assessment-guide-with-cis-v1.6-benchmark.html +++ b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke1-self-assessment-guide-with-cis-v1.6-benchmark.html @@ -5,7 +5,7 @@ RKE CIS v1.6 Benchmark - Self-Assessment Guide - Rancher v2.6 | Rancher Manager - + @@ -461,7 +461,7 @@ suggested list of security contexts, you may refer to the CIS Security Benchmark Containers.

    5.7.4 The default namespace should not be used (Automated)​

    Result: pass

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Audit Script: check_for_default_ns.sh

    #!/bin/bash

    set -eE

    handle_error() {
        echo "false"
    }

    trap 'handle_error' ERR

    count=$(kubectl get all -n default -o json | jq .items[] | jq -r 'select((.metadata.name!="kubernetes"))' | jq .metadata.name | wc -l)
    if [[ ${count} -gt 0 ]]; then
        echo "false"
        exit
    fi

    echo "true"


    Audit Execution:

    ./check_for_default_ns.sh

    Expected Result:

    'true' is equal to 'true'

    Returned Value:

    true
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-hardening-guide-with-cis-v1.6-benchmark.html b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-hardening-guide-with-cis-v1.6-benchmark.html index b058abc6741..37be1ca2052 100644 --- a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-hardening-guide-with-cis-v1.6-benchmark.html +++ b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-hardening-guide-with-cis-v1.6-benchmark.html @@ -5,7 +5,7 @@ RKE2 Hardening Guide with CIS v1.6 Benchmark | Rancher Manager - + @@ -16,7 +16,7 @@ This can be remediated by creating an etcd user and group as descri You can manually update this field on service accounts in your cluster to pass the control as described above.

    Control 5.3.2​

    Ensure that all Namespaces have Network Policies defined

    Rationale Running different applications on the same Kubernetes cluster creates a risk of one compromised application attacking a neighboring application. Network segmentation is important to ensure that containers can communicate only with those they are supposed to. A network policy is a specification of how selections of pods are allowed to communicate with each other and other network endpoints.

    Network Policies are namespace scoped. When a network policy is introduced to a given namespace, all traffic not allowed by the policy is denied. However, if there are no network policies in a namespace all traffic will be allowed into and out of the pods in that namespace.

    Remediation This can be remediated by setting profile: "cis-1.6" in RKE2 template configuration file. An example can be found below.

    Reference Hardened RKE2 Template Configuration​

    The reference template configuration is used in Rancher to create a hardened RKE2 custom cluster. This reference does not include other required cluster configuration directives which will vary depending on your environment.

    apiVersion: provisioning.cattle.io/v1
    kind: Cluster
    metadata:
      name: <replace_with_cluster_name>
      annotations:
        {}
    #    key: string
      labels:
        {}
    #    key: string
      namespace: fleet-default
    spec:
      defaultPodSecurityPolicyTemplateName: ''
      kubernetesVersion: <replace_with_kubernetes_version>
      localClusterAuthEndpoint:
        caCerts: ''
        enabled: false
        fqdn: ''
      rkeConfig:
        chartValues:
          rke2-canal:
            {}
        etcd:
          disableSnapshots: false
          s3:
    #        bucket: string
    #        cloudCredentialName: string
    #        endpoint: string
    #        endpointCA: string
    #        folder: string
    #        region: string
    #        skipSSLVerify: boolean
          snapshotRetention: 5
          snapshotScheduleCron: 0 */5 * * *
        machineGlobalConfig:
          cni: canal
        machinePools:
    #      - cloudCredentialSecretName: string
    #        controlPlaneRole: boolean
    #        displayName: string
    #        drainBeforeDelete: boolean
    #        etcdRole: boolean
    #        labels:
    #          key: string
    #        machineConfigRef:
    #          apiVersion: string
    #          fieldPath: string
    #          kind: string
    #          name: string
    #          namespace: string
    #          resourceVersion: string
    #          uid: string
    #        machineDeploymentAnnotations:
    #          key: string
    #        machineDeploymentLabels:
    #          key: string
    #        machineOS: string
    #        maxUnhealthy: string
    #        name: string
    #        nodeStartupTimeout: string
    #        paused: boolean
    #        quantity: int
    #        rollingUpdate:
    #          maxSurge: string
    #          maxUnavailable: string
    #        taints:
    #          - effect: string
    #            key: string
    #            timeAdded: string
    #            value: string
    #        unhealthyNodeTimeout: string
    #        unhealthyRange: string
    #        workerRole: boolean
        machineSelectorConfig:
          - config:
              profile: cis-1.6
              protect-kernel-defaults: true
    #      - config:
    #
    #        machineLabelSelector:
    #          matchExpressions:
    #            - key: string
    #              operator: string
    #              values:
    #                - string
    #          matchLabels:
    #            key: string
        registries:
          configs:
            {}
            #authConfigSecretName: string
    #          caBundle: string
    #          insecureSkipVerify: boolean
    #          tlsSecretName: string
          mirrors:
            {}
            #endpoint:
    #            - string
    #          rewrite:
    #            key: string
        upgradeStrategy:
          controlPlaneConcurrency: 10%
          controlPlaneDrainOptions:
    #        deleteEmptyDirData: boolean
    #        disableEviction: boolean
    #        enabled: boolean
    #        force: boolean
    #        gracePeriod: int
    #        ignoreDaemonSets: boolean
    #        ignoreErrors: boolean
    #        postDrainHooks:
    #          - annotation: string
    #        preDrainHooks:
    #          - annotation: string
    #        skipWaitForDeleteTimeoutSeconds: int
    #        timeout: int
          workerConcurrency: 10%
          workerDrainOptions:
    #        deleteEmptyDirData: boolean
    #        disableEviction: boolean
    #        enabled: boolean
    #        force: boolean
    #        gracePeriod: int
    #        ignoreDaemonSets: boolean
    #        ignoreErrors: boolean
    #        postDrainHooks:
    #          - annotation: string
    #        preDrainHooks:
    #          - annotation: string
    #        skipWaitForDeleteTimeoutSeconds: int
    #        timeout: int
    #    additionalManifest: string
    #    etcdSnapshotCreate:
    #      generation: int
    #    etcdSnapshotRestore:
    #      generation: int
    #      name: string
    #      restoreRKEConfig: string
    #    infrastructureRef:
    #      apiVersion: string
    #      fieldPath: string
    #      kind: string
    #      name: string
    #      namespace: string
    #      resourceVersion: string
    #      uid: string
    #    provisionGeneration: int
    #    rotateCertificates:
    #      generation: int
    #      services:
    #        - string
    #    rotateEncryptionKeys:
    #      generation: int
      machineSelectorConfig:
        - config: {}
    #  agentEnvVars:
    #    - name: string
    #      value: string
    #  cloudCredentialSecretName: string
    #  clusterAPIConfig:
    #    clusterName: string
    #  defaultClusterRoleForProjectMembers: string
    #  enableNetworkPolicy: boolean
    #  redeploySystemAgentGeneration: int
    __clone: true

    Conclusion​

    If you have followed this guide, your RKE2 custom cluster provisioned by Rancher will be configured to pass the CIS Kubernetes Benchmark. You can review our RKE2 CIS Benchmark Self-Assessment Guide v1.6 to understand how we verified each of the benchmarks and how you can do the same on your cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-self-assessment-guide-with-cis-v1.6-benchmark.html b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-self-assessment-guide-with-cis-v1.6-benchmark.html index d572a7eb337..6a396582fb0 100644 --- a/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-self-assessment-guide-with-cis-v1.6-benchmark.html +++ b/reference-guides/rancher-security/rancher-v2.6-hardening-guides/rke2-self-assessment-guide-with-cis-v1.6-benchmark.html @@ -5,7 +5,7 @@ RKE2 CIS v1.6 Benchmark - Self-Assessment Guide - Rancher v2.6 | Rancher Manager - + @@ -477,7 +477,7 @@ suggested list of security contexts, you may refer to the CIS Security Benchmark Containers.

    5.7.4 The default namespace should not be used (Manual)​

    Result: warn

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/security-advisories-and-cves.html b/reference-guides/rancher-security/security-advisories-and-cves.html index e2fa56e4217..343cc5ce950 100644 --- a/reference-guides/rancher-security/security-advisories-and-cves.html +++ b/reference-guides/rancher-security/security-advisories-and-cves.html @@ -5,13 +5,13 @@ Security Advisories and CVEs | Rancher Manager - +
    Version: v2.6

    Security Advisories and CVEs

    Rancher is committed to informing the community of security issues in our products. Rancher will publish security advisories and CVEs (Common Vulnerabilities and Exposures) for issues we have resolved. New security advisories are also published in Rancher's GitHub security page.

    IDDescriptionDateResolution
    CVE-2022-31247An issue was discovered in Rancher versions up to and including 2.5.15 and 2.6.6 where a flaw with authorization logic allows privilege escalation in downstream clusters through cluster role template binding (CRTB) and project role template binding (PRTB). The vulnerability can be exploited by any user who has permissions to create/edit CRTB or PRTB (such as cluster-owner, manage cluster members, project-owner, and manage project members) to gain owner permission in another project in the same cluster or in another project on a different downstream cluster.18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2021-36783It was discovered that in Rancher versions up to and including 2.5.12 and 2.6.3, there is a failure to properly sanitize credentials in cluster template answers. This failure can lead to plaintext storage and exposure of credentials, passwords, and API tokens. The exposed credentials are visible in Rancher to authenticated Cluster Owners, Cluster Members, Project Owners, and Project Members on the endpoints /v1/management.cattle.io.clusters, /v3/clusters, and /k8s/clusters/local/apis/management.cattle.io/v3/clusters.18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2021-36782An issue was discovered in Rancher versions up to and including 2.5.15 and 2.6.6 where sensitive fields like passwords, API keys, and Rancher's service account token (used to provision clusters) were stored in plaintext directly on Kubernetes objects like Clusters (e.g., cluster.management.cattle.io). Anyone with read access to those objects in the Kubernetes API could retrieve the plaintext version of those sensitive data. The issue was partially found and reported by Florian Struck (from Continum AG) and Marco Stuurman (from Shock Media B.V.).18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2022-21951This vulnerability only affects customers using Weave Container Network Interface (CNI) when configured through RKE templates. A vulnerability was discovered in Rancher versions 2.5.0 up to and including 2.5.13, and 2.6.0 up to and including 2.6.4, where a user interface (UI) issue with RKE templates does not include a value for the Weave password when Weave is chosen as the CNI. If a cluster is created based on the mentioned template, and Weave is configured as the CNI, no password will be created for network encryption in Weave; therefore, network traffic in the cluster will be sent unencrypted.24 May 2022Rancher v2.6.5 and Rancher v2.5.14
    CVE-2021-36784A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3 which allows users who have create or update permissions on Global Roles to escalate their permissions, or those of another user, to admin-level permissions. Global Roles grant users Rancher-wide permissions, such as the ability to create clusters. In the identified versions of Rancher, when users are given permission to edit or create Global Roles, they are not restricted to only granting permissions which they already posses. This vulnerability affects customers who utilize non-admin users that are able to create or edit Global Roles. The most common use case for this scenario is the restricted-admin role.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    CVE-2021-4200This vulnerability only affects customers using the restricted-admin role in Rancher. A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3 where the global-data role in cattle-global-data namespace grants write access to the Catalogs. Since each user with any level of catalog access was bound to the global-data role, this grants write access to templates (CatalogTemplates) and template versions (CatalogTemplateVersions) for any user with any level of catalog access. New users created in Rancher are by default assigned to the user role (standard user), which is not designed to grant write catalog access. This vulnerability effectively elevates the privilege of any user to write access for the catalog template and catalog template version resources.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    GHSA-wm2r-rp98-8pmhThis vulnerability only affects customers using Fleet for continuous delivery with authenticated Git and/or Helm repositories. An issue was discovered in go-getter library in versions prior to v1.5.11 that exposes SSH private keys in base64 format due to a failure in redacting such information from error messages. The vulnerable version of this library is used in Rancher through Fleet in versions of Fleet prior to v0.3.9. This issue affects Rancher versions 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3. The issue was found and reported by Dagan Henderson from Raft Engineering.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    CVE-2021-36778A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.11 and from 2.6.0 up to and including 2.6.2, where an insufficient check of the same-origin policy when downloading Helm charts from a configured private repository can lead to exposure of the repository credentials to a third-party provider. This issue only happens when the user configures access credentials to a private repository in Rancher inside Apps & Marketplace > Repositories. The issue was found and reported by Martin Andreas Ullrich.14 Apr 2022Rancher v2.6.3 and Rancher v2.5.12
    GHSA-hwm2-4ph6-w6m5A vulnerability was discovered in versions of Rancher starting 2.0 up to and including 2.6.3. The restricted pod security policy (PSP) provided in Rancher deviated from the upstream restricted policy provided in Kubernetes on account of which Rancher's PSP had runAsUser set to runAsAny, while upstream had runAsUser set to MustRunAsNonRoot. This allowed containers to run as any user, including a privileged user (root), even when Rancher's restricted policy was enforced on a project or at the cluster level.31 Mar 2022Rancher v2.6.4
    CVE-2021-36775A vulnerability was discovered in Rancher versions up to and including 2.4.17, 2.5.11 and 2.6.2. After removing a Project Role associated with a group from the project, the bindings that granted access to cluster-scoped resources for those subjects were not deleted. This was due to an incomplete authorization logic check. A user who was a member of the affected group with authenticated access to Rancher could exploit this vulnerability to access resources they shouldn't have had access to. The exposure level would depend on the original permission level granted to the affected project role. This vulnerability only affected customers using group based authentication in Rancher.31 Mar 2022Rancher v2.6.3, Rancher v2.5.12 and Rancher v2.4.18
    CVE-2021-36776A vulnerability was discovered in Rancher versions starting 2.5.0 up to and including 2.5.9, that allowed an authenticated user to impersonate any user on a cluster through an API proxy, without requiring knowledge of the impersonated user's credentials. This was due to the API proxy not dropping the impersonation header before sending the request to the Kubernetes API. A malicious user with authenticated access to Rancher could use this to impersonate another user with administrator access in Rancher, thereby gaining administrator level access to the cluster.31 Mar 2022Rancher v2.6.0 and Rancher v2.5.10
    CVE-2021-25318A vulnerability was discovered in Rancher versions 2.0 through the aforementioned fixed versions, where users were granted access to resources regardless of the resource's API group. For example, Rancher should have allowed users access to apps.catalog.cattle.io, but instead incorrectly gave access to apps.*. Resources affected in the Downstream clusters and Rancher management cluster can be found here. There is not a direct mitigation besides upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-31999A vulnerability was discovered in Rancher 2.0.0 through the aforementioned patched versions, where a malicious Rancher user could craft an API request directed at the proxy for the Kubernetes API of a managed cluster to gain access to information they do not have access to. This is done by passing the "Impersonate-User" or "Impersonate-Group" header in the Connection header, which is then correctly removed by the proxy. At this point, instead of impersonating the user and their permissions, the request will act as if it was from the Rancher management server and incorrectly return the information. The vulnerability is limited to valid Rancher users with some level of permissions on the cluster. There is not a direct mitigation besides upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-25320A vulnerability was discovered in Rancher 2.2.0 through the aforementioned patched versions, where cloud credentials weren't being properly validated through the Rancher API. Specifically through a proxy designed to communicate with cloud providers. Any Rancher user that was logged-in and aware of a cloud-credential ID that was valid for a given cloud provider, could call that cloud provider's API through the proxy API, and the cloud-credential would be attached. The exploit is limited to valid Rancher users. There is not a direct mitigation outside of upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-25313A security vulnerability was discovered on all Rancher 2 versions. When accessing the Rancher API with a browser, the URL was not properly escaped, making it vulnerable to an XSS attack. Specially crafted URLs to these API endpoints could include JavaScript which would be embedded in the page and execute in a browser. There is no direct mitigation. Avoid clicking on untrusted links to your Rancher server.2 Mar 2021Rancher v2.5.6, Rancher v2.4.14, and Rancher v2.3.11
    CVE-2019-14435This vulnerability allows authenticated users to potentially extract otherwise private data out of IPs reachable from system service containers used by Rancher. This can include but not only limited to services such as cloud provider metadata services. Although Rancher allow users to configure whitelisted domains for system service access, this flaw can still be exploited by a carefully crafted HTTP request. The issue was found and reported by Matt Belisle and Alex Stevenson at Workiva.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    CVE-2019-14436The vulnerability allows a member of a project that has access to edit role bindings to be able to assign themselves or others a cluster level role granting them administrator access to that cluster. The issue was found and reported by Michal Lipinski at Nokia.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    CVE-2019-13209The vulnerability is known as a Cross-Site Websocket Hijacking attack. This attack allows an exploiter to gain access to clusters managed by Rancher with the roles/permissions of a victim. It requires that a victim to be logged into a Rancher server and then access a third-party site hosted by the exploiter. Once that is accomplished, the exploiter is able to execute commands against the Kubernetes API with the permissions and identity of the victim. Reported by Matt Belisle and Alex Stevenson from Workiva.15 Jul 2019Rancher v2.2.5, Rancher v2.1.11 and Rancher v2.0.16
    CVE-2019-12303Project owners can inject extra fluentd logging configurations that makes it possible to read files or execute arbitrary commands inside the fluentd container. Reported by Tyler Welton from Untamed Theory.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-12274Nodes using the built-in node drivers using a file path option allows the machine to read arbitrary files including sensitive ones from inside the Rancher server container.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-11202The default admin, that is shipped with Rancher, will be re-created upon restart of Rancher despite being explicitly deleted.16 Apr 2019Rancher v2.2.2, Rancher v2.1.9 and Rancher v2.0.14
    CVE-2019-6287Project members continue to get access to namespaces from projects that they were removed from if they were added to more than one project.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11
    CVE-2018-20321Any project member with access to the default namespace can mount the netes-default service account in a pod and then use that pod to execute administrative privileged commands against the Kubernetes cluster.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11 - Rolling back from these versions or greater have specific instructions.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html b/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html index 305ceabef1a..84b3ca09dff 100644 --- a/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html +++ b/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html @@ -5,13 +5,13 @@ About rancher-selinux | Rancher Manager - +
    Version: v2.6

    About rancher-selinux

    To allow Rancher to work with SELinux, some functionality has to be manually enabled for the SELinux nodes. To help with that, Rancher provides a SELinux RPM.

    The rancher-selinux RPM only contains policies for the rancher-logging application.

    The rancher-selinux GitHub repository is here.

    Installing the rancher-selinux RPM​

    Requirement:

    The rancher-selinux RPM was tested with CentOS 7 and 8.

    1. Set up the yum repo​

    Set up the yum repo to install rancher-selinux directly on all hosts in the cluster.

    In order to use the RPM repository, on a CentOS 7 or RHEL 7 system, run the following bash snippet:

    # cat << EOF > /etc/yum.repos.d/rancher.repo 
    [rancher] 
    name=Rancher 
    baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch
    enabled=1 
    gpgcheck=1 
    gpgkey=https://rpm.rancher.io/public.key 
    EOF

    In order to use the RPM repository, on a CentOS 8 or RHEL 8 system, run the following bash snippet:

    # cat << EOF > /etc/yum.repos.d/rancher.repo 
    [rancher] 
    name=Rancher 
    baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch
    enabled=1 
    gpgcheck=1 
    gpgkey=https://rpm.rancher.io/public.key 
    EOF

    2. Installing the RPM​

    Install the RPM:

    yum -y install rancher-selinux

    Configuring the Logging Application to Work with SELinux​

    Requirement:

    Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8.

    Applications do not automatically work once the rancher-selinux RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM.

    To configure the rancher-logging chart to be SELinux aware, change global.seLinux.enabled to true in the values.yaml when installing the chart.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html b/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html index 9698f983413..9a684378260 100644 --- a/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html +++ b/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html @@ -5,13 +5,13 @@ About rke2-selinux | Rancher Manager - +
    Version: v2.6

    About rke2-selinux

    rke2-selinux provides policies for RKE2. It is installed automatically when the RKE2 installer script detects that it is running on an RPM-based distro.

    The rke2-selinux GitHub repository is here.

    For more information about installing RKE2 on SELinux-enabled hosts, see the RKE2 documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/rke1-template-example-yaml.html b/reference-guides/rke1-template-example-yaml.html index 32f9c378a87..04b9dfdb258 100644 --- a/reference-guides/rke1-template-example-yaml.html +++ b/reference-guides/rke1-template-example-yaml.html @@ -5,13 +5,13 @@ RKE1 Example YAML | Rancher Manager - +
    Version: v2.6

    RKE1 Example YAML

    Below is an example RKE template configuration file for reference.

    The YAML in the RKE template uses the same customization that is used when you create an RKE cluster. However, since the YAML is within the context of a Rancher provisioned RKE cluster, the customization from the RKE docs needs to be nested under the rancher_kubernetes_engine directive.

    #
    # Cluster Config
    #
    docker_root_dir: /var/lib/docker

    enable_cluster_alerting: false
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have alerting turned off by default,
    # but end users could still turn alerting
    # on or off.

    enable_cluster_monitoring: true
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have monitoring turned on
    # by default, but end users could still
    # turn monitoring on or off.

    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config: # Your RKE template config goes here.
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false
    windows_prefered_cluster: false
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/single-node-rancher-in-docker/advanced-options.html b/reference-guides/single-node-rancher-in-docker/advanced-options.html index f072195f54f..647e4b64f08 100644 --- a/reference-guides/single-node-rancher-in-docker/advanced-options.html +++ b/reference-guides/single-node-rancher-in-docker/advanced-options.html @@ -5,13 +5,13 @@ Advanced Options for Docker Installs | Rancher Manager - +
    Version: v2.6

    Advanced Options for Docker Installs

    Custom CA Certificate​

    If you want to configure Rancher to use a CA root certificate to be used when validating services, you would start the Rancher container sharing the directory that contains the CA root certificate.

    Use the command example to start a Rancher container with your private CA certificates mounted.

    • The volume flag (-v) should specify the host directory containing the CA root certificates.
    • The environment variable flag (-e) in combination with SSL_CERT_DIR and directory declares an environment variable that specifies the mounted CA root certificates directory location inside the container.
    • Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE.
    • Mounting a host directory inside the container can be done using -v host-source-directory:container-destination-directory or --volume host-source-directory:container-destination-directory.

    The example below is based on having the CA root certificates in the /host/certs directory on the host and mounting this directory on /container/certs inside the Rancher container.

    Privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /host/certs:/container/certs \
      -e SSL_CERT_DIR="/container/certs" \
      --privileged \
      rancher/rancher:latest

    API Audit Log​

    The API Audit Log records all the user and system transactions made through Rancher server.

    The API Audit Log writes to /var/log/auditlog inside the rancher container by default. Share that directory as a volume and set your AUDIT_LEVEL to enable the log.

    See API Audit Log for more information and options.

    Privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /var/log/rancher/auditlog:/var/log/auditlog \
      -e AUDIT_LEVEL=1 \
      --privileged \
      rancher/rancher:latest

    TLS settings​

    To set a different TLS configuration, you can use the CATTLE_TLS_MIN_VERSION and CATTLE_TLS_CIPHERS environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e CATTLE_TLS_MIN_VERSION="1.0" \
      --privileged \
      rancher/rancher:latest

    Privileged access is required.

    See TLS settings for more information and options.

    Air Gap​

    If you are visiting this page to complete an air gap installation, you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

    Example:

     <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

    Persistent Data​

    Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

    You can bind mount a host volume to this location to preserve data on the host it is running on:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /opt/rancher:/var/lib/rancher \
      --privileged \
      rancher/rancher:latest

    Privileged access is required.

    Running rancher/rancher and rancher/rancher-agent on the Same Node​

    In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the rancher/rancher container.

    If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advise to expose for the rancher/rancher container.

    Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes.

    To change the host ports mapping, replace the following part -p 80:80 -p 443:443 with -p 8080:80 -p 8443:443:

    docker run -d --restart=unless-stopped \
      -p 8080:80 -p 8443:443 \
      --privileged \
      rancher/rancher:latest

    Privileged access is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html b/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html index 7c356390e74..a586160cc15 100644 --- a/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html +++ b/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html @@ -5,13 +5,13 @@ HTTP Proxy Configuration | Rancher Manager - +
    Version: v2.6

    HTTP Proxy Configuration

    If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.

    Make sure NO_PROXY contains the network addresses, network address ranges and domains that should be excluded from using the proxy.

    Environment variablePurpose
    HTTP_PROXYProxy address to use when initiating HTTP connection(s)
    HTTPS_PROXYProxy address to use when initiating HTTPS connection(s)
    NO_PROXYNetwork address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s)
    Important:

    NO_PROXY must be in uppercase to use network range (CIDR) notation.

    Docker Installation​

    Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE. Required values for NO_PROXY in a Docker Installation are:

    • localhost
    • 127.0.0.1
    • 0.0.0.0
    • 10.0.0.0/8
    • cattle-system.svc
    • .svc
    • .cluster.local

    The example below is based on a proxy server accessible at http://192.168.0.1:3128, and excluding usage the proxy when accessing network range 192.168.10.0/24 and every hostname under the domain example.com.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e HTTP_PROXY="http://192.168.10.1:3128" \
      -e HTTPS_PROXY="http://192.168.10.1:3128" \
      -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,192.168.10.0/24,.svc,.cluster.local,example.com" \
      --privileged \
      rancher/rancher:latest

    Privileged access is required.

    Air-gapped proxy configuration​

    New in v2.6.4

    You can now provision node driver clusters from an air-gapped cluster configured to use a proxy for outbound connections.

    In addition to setting the default rules for a proxy server as shown above, you will need to add additional rules, shown below, to provision node driver clusters from a proxied Rancher environment.

    You will configure your filepath according to your setup, e.g., /etc/apt/apt.conf.d/proxy.conf:

    acl SSL_ports port 22
    acl SSL_ports port 2376

    acl Safe_ports port 22      # ssh
    acl Safe_ports port 2376    # docker port
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/system-tools.html b/reference-guides/system-tools.html index afbb6adb19d..0b210f9b41d 100644 --- a/reference-guides/system-tools.html +++ b/reference-guides/system-tools.html @@ -5,13 +5,13 @@ System Tools | Rancher Manager - +
    Version: v2.6

    System Tools

    note

    System Tools has been deprecated since June 2022.

    Logs

    Please use logs-collector to collect logs from your cluster.

    Stats

    If you want to replicate the stats command, you can run the following command on your cluster nodes:

    note

    This command below requires the package sysstat on the cluster node.

    /usr/bin/sar -u -r -F 1 1

    Remove

    Please use the Rancher Cleanup tool.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/user-settings/api-keys.html b/reference-guides/user-settings/api-keys.html index 58f1ef04323..9d36988de84 100644 --- a/reference-guides/user-settings/api-keys.html +++ b/reference-guides/user-settings/api-keys.html @@ -5,13 +5,13 @@ API Keys | Rancher Manager - +
    Version: v2.6

    API Keys

    API Keys and User Authentication​

    If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI.

    An API key is also required for using Rancher CLI.

    API Keys are composed of four components:

    • Endpoint: This is the IP address and path that other applications use to send requests to the Rancher API.
    • Access Key: The token's username.
    • Secret Key: The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together.
    • Bearer Token: The token username and password concatenated together. Use this string for applications that prompt you for one authentication string.
    note

    Users may opt to enable token hashing.

    Creating an API Key​

    1. Select User Avatar > Account & API Keys from upper right corner.

    2. Click Create API Key.

    3. Optional: Enter a description for the API key and select an expiration period or a scope. We recommend setting an expiration date.

      The API key won't be valid after expiration. Shorter expiration periods are more secure.

      Expiration period will be bound by v3/settings/auth-token-max-ttl-minutes. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period.

      A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See Authorized Cluster Endpoints for more information.

    4. Click Create.

      Step Result: Your API Key is created. Your API Endpoint, Access Key, Secret Key, and Bearer Token are displayed.

      Use the Bearer Token to authenticate with Rancher CLI.

    5. Copy the information displayed to a secure location. This information is only displayed once, so if you lose your key, you'll have to make a new one.

    What's Next?​

    • Enter your API key information into the application that will send requests to the Rancher API.
    • Learn more about the Rancher endpoints and parameters by selecting View in API for an object in the Rancher UI.
    • API keys are used for API calls and Rancher CLI.

    Deleting API Keys​

    If you need to revoke an API key, delete it. You should delete API keys:

    • That may have been compromised.
    • That have expired.

    To delete an API, select the stale key and click Delete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/user-settings/manage-cloud-credentials.html b/reference-guides/user-settings/manage-cloud-credentials.html index 7d10a0e75b2..5cad891ed3c 100644 --- a/reference-guides/user-settings/manage-cloud-credentials.html +++ b/reference-guides/user-settings/manage-cloud-credentials.html @@ -5,13 +5,13 @@ Managing Cloud Credentials | Rancher Manager - +
    Version: v2.6

    Managing Cloud Credentials

    When you create a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node.

    Node templates can use cloud credentials to access the credential information required to provision nodes in the infrastructure providers. The same cloud credential can be used by multiple node templates. By using a cloud credential, you do not have to re-enter access keys for the same cloud provider. Cloud credentials are stored as Kubernetes secrets.

    Cloud credentials are only used by node templates if there are fields marked as password. The default active node drivers have their account access fields marked as password, but there may be some inactive node drivers, which are not using them yet. These node drivers will not use cloud credentials.

    You can create cloud credentials in two contexts:

    All cloud credentials are bound to the user profile of who created it. They cannot be shared across users.

    Creating a Cloud Credential from User Settings​

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Click Create.
    4. Click a cloud credential type. The values of this dropdown is based on the active node drivers in Rancher.
    5. Enter a name for the cloud credential.
    6. Based on the selected cloud credential type, enter the required values to authenticate with the infrastructure provider.
    7. Click Create.

    Result: The cloud credential is created and can immediately be used to create node templates.

    Updating a Cloud Credential​

    When access credentials are changed or compromised, updating a cloud credential allows you to rotate those credentials while keeping the same node template.

    1. Click ☰ > Cluster Management.
    2. Click Cloud Credentials.
    3. Choose the cloud credential you want to edit and click the ⋮ > Edit Config.
    4. Update the credential information and click Save.

    Result: The cloud credential is updated with the new access credentials. All existing node templates using this cloud credential will automatically use the updated information whenever new nodes are added.

    Deleting a Cloud Credential​

    In order to delete cloud credentials, there must not be any node template associated with it. If you are unable to delete the cloud credential, delete any node templates that are still associated to that cloud credential.

    1. Click ☰ > Cluster Management.

    2. Click Cloud Credentials.

    3. You can either individually delete a cloud credential or bulk delete.

      • To individually delete one, choose the cloud credential you want to edit and click the ⋮ > Delete.
      • To bulk delete cloud credentials, select one or more cloud credentials from the list. Click Delete.

    4. Confirm that you want to delete these cloud credentials.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/user-settings/manage-node-templates.html b/reference-guides/user-settings/manage-node-templates.html index 4e52037562f..10e6eb173b9 100644 --- a/reference-guides/user-settings/manage-node-templates.html +++ b/reference-guides/user-settings/manage-node-templates.html @@ -5,13 +5,13 @@ Managing Node Templates | Rancher Manager - +
    Version: v2.6

    Managing Node Templates

    When you provision a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node. You can create node templates in two contexts:

    When you create a node template, it is bound to your user profile. Node templates cannot be shared among users. You can delete stale node templates that you no longer user from your user settings.

    Creating a Node Template​

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Click Add Template.
    4. Select one of the cloud providers available. Then follow the instructions on screen to configure the template.

    Result: The template is configured. You can use the template later when you provision a node pool cluster.

    Updating a Node Template​

    1. Click ☰ > Cluster Management.

    2. Click RKE1 Configuration > Node Templates.

    3. Choose the node template that you want to edit and click the ⋮ > Edit.

      note

      The default active node drivers and any node driver, that has fields marked as password, are required to use cloud credentials.

    4. Edit the required information and click Save.

    Result: The node template is updated. All node pools using this node template will automatically use the updated information when new nodes are added.

    Cloning Node Templates​

    When creating new node templates from your user settings, you can clone an existing template and quickly update its settings rather than creating a new one from scratch. Cloning templates saves you the hassle of re-entering access keys for the cloud provider.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Find the template you want to clone. Then select ⋮ > Clone.
    4. Complete the rest of the form.

    Result: The template is cloned and configured. You can use the template later when you provision a node pool cluster.

    Deleting a Node Template​

    When you no longer use a node template, you can delete it from your user settings.

    1. Click ☰ > Cluster Management.
    2. Click RKE1 Configuration > Node Templates.
    3. Select one or more template from the list. Then click Delete. Confirm the delete when prompted.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/reference-guides/user-settings/user-preferences.html b/reference-guides/user-settings/user-preferences.html index 4540d5bfbaa..e81d3fdb1b3 100644 --- a/reference-guides/user-settings/user-preferences.html +++ b/reference-guides/user-settings/user-preferences.html @@ -5,13 +5,13 @@ User Preferences | Rancher Manager - +
    Version: v2.6

    User Preferences

    Each user can choose preferences to personalize their Rancher experience. To change preference settings, open the User Settings menu and then select Preferences.

    Theme​

    Choose your background color for the Rancher UI. If you choose Auto, the background color changes from light to dark at 6 PM, and then changes back at 6 AM.

    My Account​

    This section displays the Name (your display name) and Username (your login) used for your session. To change your login's current password, click the Change Password button.

    Table Row per Page​

    On pages that display system objects like clusters or deployments in a table, you can set the number of objects that display on the page before you must paginate. The default setting is 50.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/search.html b/search.html index 64392049f10..1eff1bc0740 100644 --- a/search.html +++ b/search.html @@ -5,13 +5,13 @@ Search the documentation | Rancher Manager - +

    Search the documentation

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/security/security-scan.html b/security/security-scan.html index a564e7e08d9..ca71d8bd3c5 100644 --- a/security/security-scan.html +++ b/security/security-scan.html @@ -5,13 +5,13 @@ Security Scans | Rancher Manager - +
    Version: v2.6

    Security Scans

    The documentation about CIS security scans has moved here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting.html b/troubleshooting.html index 5604ff94397..678bd358e74 100644 --- a/troubleshooting.html +++ b/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
    Version: v2.6

    Troubleshooting

    This section contains information to help you troubleshoot issues when using Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html b/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html index d9a8d9b2edc..e564c2f44fb 100644 --- a/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html +++ b/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html @@ -5,13 +5,13 @@ Troubleshooting Controlplane Nodes | Rancher Manager - +
    Version: v2.6

    Troubleshooting Controlplane Nodes

    This section applies to nodes with the controlplane role.

    Check if the Controlplane Containers are Running

    There are three specific containers launched on nodes with the controlplane role:

    • kube-apiserver
    • kube-controller-manager
    • kube-scheduler

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kube-apiserver|kube-controller-manager|kube-scheduler'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    26c7159abbcc        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-apiserver
    f3d287ca4549        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-scheduler
    bdf3898b8063        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-controller-manager

    Controlplane Container Logging

    note

    If you added multiple nodes with the controlplane role, both kube-controller-manager and kube-scheduler use a leader election process to determine the leader. Only the current leader will log the performed actions. See Kubernetes leader election how to retrieve the current leader.

    The logging of the containers can contain information on what the problem could be.

    docker logs kube-apiserver
    docker logs kube-controller-manager
    docker logs kube-scheduler

    RKE2 Server Logging

    If Rancher provisions an RKE2 cluster that can't communicate with Rancher, you can run this command on a server node in the downstream cluster to get the RKE2 server logs:

    journalctl -u rke2-server -f
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html b/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html index e4cb866fbac..b1dbb421770 100644 --- a/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html +++ b/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html @@ -5,13 +5,13 @@ Troubleshooting etcd Nodes | Rancher Manager - +
    Version: v2.6

    Troubleshooting etcd Nodes

    This section contains commands and tips for troubleshooting nodes with the etcd role.

    Checking if the etcd Container is Running​

    The container for etcd should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=etcd$

    Example output:

    CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS              PORTS               NAMES
    605a124503b9        rancher/coreos-etcd:v3.2.18   "/usr/local/bin/et..."   2 hours ago         Up 2 hours                              etcd

    etcd Container Logging​

    The logging of the container can contain information on what the problem could be.

    docker logs etcd
    LogExplanation
    health check for peer xxx could not connect: dial tcp IP:2380: getsockopt: connection refusedA connection to the address shown on port 2380 cannot be established. Check if the etcd container is running on the host with the address shown.
    xxx is starting a new election at term xThe etcd cluster has lost its quorum and is trying to establish a new leader. This can happen when the majority of the nodes running etcd go down/unreachable.
    connection error: desc = "transport: Error while dialing dial tcp 0.0.0.0:2379: i/o timeout"; Reconnecting to {0.0.0.0:2379 0 <nil>}The host firewall is preventing network communication.
    rafthttp: request cluster ID mismatchThe node with the etcd instance logging rafthttp: request cluster ID mismatch is trying to join a cluster that has already been formed with another peer. The node should be removed from the cluster, and re-added.
    rafthttp: failed to find memberThe cluster state (/var/lib/etcd) contains wrong information to join the cluster. The node should be removed from the cluster, the state directory should be cleaned and the node should be re-added.

    etcd Cluster and Connectivity Checks​

    The address where etcd is listening depends on the address configuration of the host etcd is running on. If an internal address is configured for the host etcd is running on, the endpoint for etcdctl needs to be specified explicitly. If any of the commands respond with Error: context deadline exceeded, the etcd instance is unhealthy (either quorum is lost or the instance is not correctly joined in the cluster)

    Check etcd Members on all Nodes​

    Output should contain all the nodes with the etcd role and the output should be identical on all nodes.

    Command:

    docker exec etcd etcdctl member list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list"

    Example output:

    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001

    Check Endpoint Status​

    The values for RAFT TERM should be equal and RAFT INDEX should be not be too far apart from each other.

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 | 333ef673fc4add56 |  3.2.18 |   24 MB |     false |        72 |      66887 |
    | https://IP:2379 | 5feed52d940ce4cf |  3.2.18 |   24 MB |      true |        72 |      66887 |
    | https://IP:2379 | db6b3bdb559a848d |  3.2.18 |   25 MB |     false |        72 |      66887 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Check Endpoint Health​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint health

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint health --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")

    Example output:

    https://IP:2379 is healthy: successfully committed proposal: took = 2.113189ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.649963ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.451201ms

    Check Connectivity on Port TCP/2379​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5"); do
       echo "Validating connection to ${endpoint}/health"
       docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5"); do
      echo "Validating connection to ${endpoint}/health";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Example output:

    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}

    Check Connectivity on Port TCP/2380​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Example output:

    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}

    etcd Alarms​

    etcd will trigger alarms, for instance when it runs out of space.

    Command:

    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output when NOSPACE alarm is triggered:

    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE

    etcd Space Errors​

    Related error messages are etcdserver: mvcc: database space exceeded or applying raft message exceeded backend quota. Alarm NOSPACE will be triggered.

    Resolutions:

    Compact the Keyspace​

    Command:

    rev=$(docker exec etcd etcdctl endpoint status --write-out json | egrep -o '"revision":[0-9]*' | egrep -o '[0-9]*')
    docker exec etcd etcdctl compact "$rev"

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    rev=$(docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT endpoint status --write-out json | egrep -o '\"revision\":[0-9]*' | egrep -o '[0-9]*'")
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT compact \"$rev\""

    Example output:

    compacted revision xxx

    Defrag All etcd Members​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl defrag

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl defrag --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")"

    Example output:

    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]

    Check Endpoint Status​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table"

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 |  e973e4419737125 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | 4a509c997b26c206 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | b217e736575e9dd3 |  3.2.18 |  553 kB |      true |        32 |    2449410 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Disarm Alarm​

    After verifying that the DB size went down after compaction and defragmenting, the alarm needs to be disarmed for etcd to allow writes again.

    Command:

    docker exec etcd etcdctl alarm list
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm disarm"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output:

    docker exec etcd etcdctl alarm list
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Log Level​

    The log level of etcd can be changed dynamically via the API. You can configure debug logging using the commands below.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    To reset the log level back to the default (INFO), you can use the following command.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    etcd Content​

    If you want to investigate the contents of your etcd, you can either watch streaming events or you can query etcd directly, see below for examples.

    Watch Streaming Events​

    Command:

    docker exec etcd etcdctl watch --prefix /registry

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT watch --prefix /registry

    If you only want to see the affected keys (and not the binary data), you can append | grep -a ^/registry to the command to filter for keys only.

    Query etcd Directly​

    Command:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT get /registry --prefix=true --keys-only

    You can process the data to get a summary of count per key, using the command below:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only | grep -v ^$ | awk -F'/' '{ if ($3 ~ /cattle.io/) {h[$3"/"$4]++} else { h[$3]++ }} END { for(k in h) print h[k], k }' | sort -nr

    Replacing Unhealthy etcd Nodes​

    When a node in your etcd cluster becomes unhealthy, the recommended approach is to fix or remove the failed or unhealthy node before adding a new etcd node to the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html b/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html index be5e3db064b..acbaa9b546f 100644 --- a/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html +++ b/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html @@ -5,13 +5,13 @@ Troubleshooting nginx-proxy | Rancher Manager - +
    Version: v2.6

    Troubleshooting nginx-proxy

    The nginx-proxy container is deployed on every node that does not have the controlplane role. It provides access to all the nodes with the controlplane role by dynamically generating the NGINX configuration based on available nodes with the controlplane role.

    Check if the Container is Running

    The container is called nginx-proxy and should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=nginx-proxy

    Example output:

    docker ps -a -f=name=nginx-proxy
    CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS               NAMES
    c3e933687c0e        rancher/rke-tools:v0.1.15   "nginx-proxy CP_HO..."   3 hours ago         Up 3 hours                              nginx-proxy

    Check Generated NGINX Configuration

    The generated configuration should include the IP addresses of the nodes with the controlplane role. The configuration can be checked using the following command:

    docker exec nginx-proxy cat /etc/nginx/nginx.conf

    Example output:

    error_log stderr notice;

    worker_processes auto;
    events {
      multi_accept on;
      use epoll;
      worker_connections 1024;
    }

    stream {
            upstream kube_apiserver {

                server ip_of_controlplane_node1:6443;

                server ip_of_controlplane_node2:6443;

            }

            server {
                listen        6443;
                proxy_pass    kube_apiserver;
                proxy_timeout 30;
                proxy_connect_timeout 2s;

            }

    }

    nginx-proxy Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs nginx-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html b/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html index e32dc6ed9ae..0da72100d69 100644 --- a/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html +++ b/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html @@ -5,13 +5,13 @@ Troubleshooting Worker Nodes and Generic Components | Rancher Manager - +
    Version: v2.6

    Troubleshooting Worker Nodes and Generic Components

    This section applies to every node as it includes components that run on nodes with any role.

    Check if the Containers are Running

    There are two specific containers launched on nodes with the worker role:

    • kubelet
    • kube-proxy

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kubelet|kube-proxy'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    158d0dcc33a5        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-proxy
    a30717ecfb55        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kubelet

    Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs kubelet
    docker logs kube-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/dns.html b/troubleshooting/other-troubleshooting-tips/dns.html index 795ed95ff63..6d0f2a0dd05 100644 --- a/troubleshooting/other-troubleshooting-tips/dns.html +++ b/troubleshooting/other-troubleshooting-tips/dns.html @@ -5,13 +5,13 @@ DNS | Rancher Manager - +
    Version: v2.6

    DNS

    The commands/steps listed on this page can be used to check name resolution issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Before running the DNS checks, check the default DNS provider for your cluster and make sure that the overlay network is functioning correctly as this can also be the reason why DNS resolution (partly) fails.

    Check if DNS pods are running​

    kubectl -n kube-system get pods -l k8s-app=kube-dns

    Example output when using CoreDNS:

    NAME                       READY   STATUS    RESTARTS   AGE
    coredns-799dffd9c4-6jhlz   1/1     Running   0          76m

    Example output when using kube-dns:

    NAME                        READY   STATUS    RESTARTS   AGE
    kube-dns-5fd74c7488-h6f7n   3/3     Running   0          4m13s

    Check if the DNS service is present with the correct cluster-ip​

    kubectl -n kube-system get svc -l k8s-app=kube-dns
    NAME               TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)         AGE
    service/kube-dns   ClusterIP   10.43.0.10   <none>        53/UDP,53/TCP   4m13s

    Check if domain names are resolving​

    Check if internal cluster names are resolving (in this example, kubernetes.default), the IP shown after Server: should be the same as the CLUSTER-IP from the kube-dns service.

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes.default

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      kubernetes.default
    Address 1: 10.43.0.1 kubernetes.default.svc.cluster.local
    pod "busybox" deleted

    Check if external names are resolving (in this example, www.google.com)

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup www.google.com

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      www.google.com
    Address 1: 2a00:1450:4009:80b::2004 lhr35s04-in-x04.1e100.net
    Address 2: 216.58.211.100 ams15s32-in-f4.1e100.net
    pod "busybox" deleted

    If you want to check resolving of domain names on all of the hosts, execute the following steps:

    1. Save the following file as ds-dnstest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: dnstest
      spec:
        selector:
            matchLabels:
              name: dnstest
        template:
          metadata:
            labels:
              name: dnstest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: busybox:1.28
              imagePullPolicy: Always
              name: alpine
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f ds-dnstest.yml

    3. Wait until kubectl rollout status ds/dnstest -w returns: daemon set "dnstest" successfully rolled out.

    4. Configure the environment variable DOMAIN to a fully qualified domain name (FQDN) that the host should be able to resolve (www.google.com is used as an example) and run the following command to let each container on every host resolve the configured domain name (it's a single line command).

      export DOMAIN=www.google.com; echo "=> Start DNS resolve test"; kubectl get pods -l name=dnstest --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do kubectl exec $pod -- /bin/sh -c "nslookup $DOMAIN > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $host cannot resolve $DOMAIN; fi; done; echo "=> End DNS resolve test"

    5. When this command has finished running, the output indicating everything is correct is:

      => Start DNS resolve test
      => End DNS resolve test

    If you see error in the output, that means that the mentioned host(s) is/are not able to resolve the given FQDN.

    Example error output of a situation where host with IP 209.97.182.150 had the UDP ports blocked.

    => Start DNS resolve test
    command terminated with exit code 1
    209.97.182.150 cannot resolve www.google.com
    => End DNS resolve test

    Cleanup the alpine DaemonSet by running kubectl delete ds/dnstest.

    CoreDNS specific​

    Check CoreDNS logging​

    kubectl -n kube-system logs -l k8s-app=kube-dns

    Check configuration​

    CoreDNS configuration is stored in the configmap coredns in the kube-system namespace.

    kubectl -n kube-system get configmap coredns -o go-template={{.data.Corefile}}

    Check upstream nameservers in resolv.conf​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for CoreDNS. You can check this file on the host or run the following Pod with dnsPolicy set to Default, which will inherit the /etc/resolv.conf from the host it is running on.

    kubectl run -i --restart=Never --rm test-${RANDOM} --image=ubuntu --overrides='{"kind":"Pod", "apiVersion":"v1", "spec": {"dnsPolicy":"Default"}}' -- sh -c 'cat /etc/resolv.conf'

    Enable query logging​

    Enabling query logging can be done by enabling the log plugin in the Corefile configuration in the configmap coredns. You can do so by using kubectl -n kube-system edit configmap coredns or use the command below to replace the configuration in place:

    kubectl get configmap -n kube-system coredns -o json | sed -e 's_loadbalance_log\\n    loadbalance_g' | kubectl apply -f -

    All queries will now be logged and can be checked using the command in Check CoreDNS logging.

    kube-dns specific​

    Check upstream nameservers in kubedns container​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for kube-dns. Sometimes the host will run a local caching DNS nameserver, which means the address in /etc/resolv.conf will point to an address in the loopback range (127.0.0.0/8) which will be unreachable by the container. In case of Ubuntu 18.04, this is done by systemd-resolved. We detect if systemd-resolved is running, and will automatically use the /etc/resolv.conf file with the correct upstream nameservers (which is located at /run/systemd/resolve/resolv.conf).

    Use the following command to check the upstream nameservers used by the kubedns container:

    kubectl -n kube-system get pods -l k8s-app=kube-dns --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do echo "Pod ${pod} on host ${host}"; kubectl -n kube-system exec $pod -c kubedns cat /etc/resolv.conf; done

    Example output:

    Pod kube-dns-667c7cb9dd-z4dsf on host x.x.x.x
    nameserver 1.1.1.1
    nameserver 8.8.4.4

    If the output shows an address in the loopback range (127.0.0.0/8), you can correct this in two ways:

    • Make sure the correct nameservers are listed in /etc/resolv.conf on your nodes in the cluster, please consult your operating system documentation on how to do this. Make sure you execute this before provisioning a cluster, or reboot the nodes after making the modification.
    • Configure the kubelet to use a different file for resolving names, by using extra_args as shown below (where /run/resolvconf/resolv.conf is the file with the correct nameservers):
    services:
      kubelet:
        extra_args:
          resolv-conf: "/run/resolvconf/resolv.conf"
    note

    As the kubelet is running inside a container, the path for files located in /etc and /usr are in /host/etc and /host/usr inside the kubelet container.

    See Editing Cluster as YAML how to apply this change. When the provisioning of the cluster has finished, you have to remove the kube-dns pod to activate the new setting in the pod:

    kubectl delete pods -n kube-system -l k8s-app=kube-dns
    pod "kube-dns-5fd74c7488-6pwsf" deleted

    Try to resolve name again using Check if domain names are resolving.

    If you want to check the kube-dns configuration in your cluster (for example, to check if there are different upstream nameservers configured), you can run the following command to list the kube-dns configuration:

    kubectl -n kube-system get configmap kube-dns -o go-template='{{range $key, $value := .data}}{{ $key }}{{":"}}{{ $value }}{{"\n"}}{{end}}'

    Example output:

    upstreamNameservers:["1.1.1.1"]
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html b/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html index 2b61982b1aa..0659470f0aa 100644 --- a/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html +++ b/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html @@ -5,13 +5,13 @@ Rotation of Expired Webhook Certificates | Rancher Manager - +
    Version: v2.6

    Rotation of Expired Webhook Certificates

    For Rancher versions that have rancher-webhook installed, certain versions created certificates that will expire after one year. It will be necessary for you to rotate your webhook certificate if the certificate did not renew.

    In Rancher v2.6.3 and up, rancher-webhook deployments will automatically renew their TLS certificate when it is within 30 or fewer days of its expiration date. If you are using v2.6.2 or below, there are two methods to work around this issue:

    1. Users with cluster access, run the following commands:​
    kubectl delete secret -n cattle-system cattle-webhook-tls
    kubectl delete mutatingwebhookconfigurations.admissionregistration.k8s.io --ignore-not-found=true rancher.cattle.io
    kubectl delete pod -n cattle-system -l app=rancher-webhook
    2. Users with no cluster access via kubectl:​

    1. Delete the cattle-webhook-tls secret in the cattle-system namespace in the local cluster.

    2. Delete the rancher.cattle.io mutating webhook

    3. Delete the rancher-webhook pod in the cattle-system namespace in the local cluster.

    note

    The webhook certificate expiration issue is not specific to cattle-webhook-tls as listed in the examples. You will fill in your expired certificate secret accordingly.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html b/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html index fb3625b944c..2fe88621245 100644 --- a/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html +++ b/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html @@ -5,13 +5,13 @@ Kubernetes Resources | Rancher Manager - +
    Version: v2.6

    Kubernetes Resources

    The commands/steps listed on this page can be used to check the most important Kubernetes resources and apply to Rancher Launched Kubernetes clusters.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Nodes​

    Get nodes​

    Run the command below and check the following:

    • All nodes in your cluster should be listed, make sure there is not one missing.
    • All nodes should have the Ready status (if not in Ready state, check the kubelet container logs on that node using docker logs kubelet)
    • Check if all nodes report the correct version.
    • Check if OS/Kernel/Docker values are shown as expected (possibly you can relate issues due to upgraded OS/Kernel/Docker)
    kubectl get nodes -o wide

    Example output:

    NAME             STATUS   ROLES          AGE   VERSION   INTERNAL-IP      EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME
    controlplane-0   Ready    controlplane   31m   v1.13.5   138.68.188.91    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    etcd-0           Ready    etcd           31m   v1.13.5   138.68.180.33    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    worker-0         Ready    worker         30m   v1.13.5   139.59.179.88    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5

    Get node conditions​

    Run the command below to list nodes with Node Conditions

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{end}}'

    Run the command below to list nodes with Node Conditions that are active that could prevent normal operation.

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{if ne .type "Ready"}}{{if eq .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{else}}{{if ne .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{": "}}{{.status}}{{"\n"}}{{end}}{{end}}{{end}}{{end}}'

    Example output:

    worker-0: DiskPressure:True

    Kubernetes leader election​

    Kubernetes Controller Manager leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-controller-manager endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-controller-manager -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Kubernetes Scheduler leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-scheduler endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-scheduler -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Ingress Controller​

    The default Ingress Controller is NGINX and is deployed as a DaemonSet in the ingress-nginx namespace. The pods are only scheduled to nodes with the worker role.

    Check if the pods are running on all nodes:

    kubectl -n ingress-nginx get pods -o wide

    Example output:

    kubectl -n ingress-nginx get pods -o wide
    NAME                                    READY     STATUS    RESTARTS   AGE       IP               NODE
    default-http-backend-797c5bc547-kwwlq   1/1       Running   0          17m       x.x.x.x          worker-1
    nginx-ingress-controller-4qd64          1/1       Running   0          14m       x.x.x.x          worker-1
    nginx-ingress-controller-8wxhm          1/1       Running   0          13m       x.x.x.x          worker-0

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n ingress-nginx describe pods -l app=ingress-nginx

    Pod container logs​

    The below command can show the logs of all the pods labeled "app=ingress-nginx", but it will display only 10 lines of log because of the restrictions of the kubectl logs command. Refer to --tail of kubectl logs -h for more information.

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    If the full log is needed, specify the pod name in the trailing command:

    kubectl -n ingress-nginx logs <pod name>

    Namespace events​

    kubectl -n ingress-nginx get events

    Debug logging​

    To enable debug logging:

    kubectl -n ingress-nginx patch ds nginx-ingress-controller --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--v=5"}]'

    Check configuration​

    Retrieve generated configuration in each pod:

    kubectl -n ingress-nginx get pods -l app=ingress-nginx --no-headers -o custom-columns=.NAME:.metadata.name | while read pod; do kubectl -n ingress-nginx exec $pod -- cat /etc/nginx/nginx.conf; done

    Rancher agents​

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes (cluster provisioning via cattle-node-agent) is done through Rancher agents.

    cattle-node-agent​

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent

    Jobs and Pods​

    Check that pods or jobs have status Running/Completed​

    To check, run the command:

    kubectl get pods --all-namespaces

    If a pod is not in Running state, you can dig into the root cause by running:

    Describe pod​

    kubectl describe pod POD_NAME -n NAMESPACE

    Pod container logs​

    kubectl logs POD_NAME -n NAMESPACE

    If a job is not in Completed state, you can dig into the root cause by running:

    Describe job​

    kubectl describe job JOB_NAME -n NAMESPACE

    Logs from the containers of pods of the job​

    kubectl logs -l job-name=JOB_NAME -n NAMESPACE

    Evicted pods​

    Pods can be evicted based on eviction signals.

    Retrieve a list of evicted pods (podname and namespace):

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}'

    To delete all evicted pods:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace delete pod $epod; done

    Retrieve a list of evicted pods, scheduled node and the reason:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace get pod $epod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,MSG:.status.message; done

    Job does not complete​

    If you have enabled Istio, and you are having issues with a Job you deployed not completing, you will need to add an annotation to your pod using these steps.

    Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. This is a temporary workaround and will disable Istio for any traffic to/from the annotated Pod. Keep in mind this may not allow you to continue to use a Job for integration testing, as the Job will not have access to the service mesh.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/logging.html b/troubleshooting/other-troubleshooting-tips/logging.html index e237c9d8571..97def7582ec 100644 --- a/troubleshooting/other-troubleshooting-tips/logging.html +++ b/troubleshooting/other-troubleshooting-tips/logging.html @@ -5,13 +5,13 @@ Logging | Rancher Manager - +
    Version: v2.6

    Logging

    The following log levels are used in Rancher:

    NameDescription
    infoLogs informational messages. This is the default log level.
    debugLogs more detailed messages that can be used to debug.
    traceLogs very detailed messages on internal functions. This is very verbose and can contain sensitive information.

    How to configure a log level​

    • Kubernetes install
    • Configure debug log level
    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set debug; done
    OK
    OK
    OK
    $ kubectl -n cattle-system logs -l app=rancher -c rancher
    • Configure info log level
    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set info; done
    OK
    OK
    OK
    • Docker Install
    • Configure debug log level
    $ docker exec -ti <container_id> loglevel --set debug
    OK
    $ docker logs -f <container_id>
    • Configure info log level
    $ docker exec -ti <container_id> loglevel --set info
    OK
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/networking.html b/troubleshooting/other-troubleshooting-tips/networking.html index 3cd2260988b..896b22481da 100644 --- a/troubleshooting/other-troubleshooting-tips/networking.html +++ b/troubleshooting/other-troubleshooting-tips/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
    Version: v2.6

    Networking

    The commands/steps listed on this page can be used to check networking related issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Double check if all the required ports are opened in your (host) firewall​

    Double check if all the required ports are opened in your (host) firewall. The overlay network uses UDP in comparison to all other required ports which are TCP.

    Check if overlay network is functioning correctly​

    The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from NODE_1 to NODE_2. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.

    To test the overlay network, you can launch the following DaemonSet definition. This will run a swiss-army-knife container on every host (image was developed by Rancher engineers and can be found here: https://github.com/rancherlabs/swiss-army-knife), which we will use to run a ping test between containers on all hosts.

    note

    This container does not support ARM nodes, such as a Raspberry Pi. This will be seen in the pod logs as exec user process caused: exec format error.

    1. Save the following file as overlaytest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: overlaytest
      spec:
        selector:
            matchLabels:
              name: overlaytest
        template:
          metadata:
            labels:
              name: overlaytest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: rancherlabs/swiss-army-knife
              imagePullPolicy: Always
              name: overlaytest
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f overlaytest.yml

    3. Wait until kubectl rollout status ds/overlaytest -w returns: daemon set "overlaytest" successfully rolled out.

    4. Run the following script, from the same location. It will have each overlaytest container on every host ping each other:

      #!/bin/bash
      echo "=> Start network overlay test"
        kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' |
        while read spod shost
          do kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' |
          while read tip thost
            do kubectl --request-timeout='10s' exec $spod -c overlaytest -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1"
              RC=$?
              if [ $RC -ne 0 ]
                then echo FAIL: $spod on $shost cannot reach pod IP $tip on $thost
                else echo $shost can reach $thost
              fi
          done
        done
      echo "=> End network overlay test"

    5. When this command has finished running, it will output the state of each route:

      => Start network overlay test
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.7.3 on wk2
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.0.5 on cp1
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.2.12 on wk1
      command terminated with exit code 1
      FAIL: overlaytest-v4qkl on cp1 cannot reach pod IP 10.42.7.3 on wk2
      cp1 can reach cp1
      cp1 can reach wk1
      command terminated with exit code 1
      FAIL: overlaytest-xpxwp on wk1 cannot reach pod IP 10.42.7.3 on wk2
      wk1 can reach cp1
      wk1 can reach wk1
      => End network overlay test

      If you see error in the output, there is some issue with the route between the pods on the two hosts. In the above output the node wk2 has no connectivity over the overlay network. This could be because the required ports for overlay networking are not opened for wk2.

    6. You can now clean up the DaemonSet by running kubectl delete ds/overlaytest.

    Check if MTU is correctly configured on hosts and on peering/tunnel appliances/devices​

    When the MTU is incorrectly configured (either on hosts running Rancher, nodes in created/imported clusters or on appliances/devices in between), error messages will be logged in Rancher and in the agents, similar to:

    • websocket: bad handshake
    • Failed to connect to proxy
    • read tcp: i/o timeout

    See Google Cloud VPN: MTU Considerations for an example how to configure MTU correctly when using Google Cloud VPN between Rancher and cluster nodes.

    Resolved issues​

    Overlay network broken when using Canal/Flannel due to missing node annotations​

    GitHub issue#13644
    Resolved inv2.1.2

    To check if your cluster is affected, the following command will list nodes that are broken (this command requires jq to be installed):

    kubectl get nodes -o json | jq '.items[].metadata | select(.annotations["flannel.alpha.coreos.com/public-ip"] == null or .annotations["flannel.alpha.coreos.com/kube-subnet-manager"] == null or .annotations["flannel.alpha.coreos.com/backend-type"] == null or .annotations["flannel.alpha.coreos.com/backend-data"] == null) | .name'

    If there is no output, the cluster is not affected.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/rancher-ha.html b/troubleshooting/other-troubleshooting-tips/rancher-ha.html index 3c7952ea237..0440772c820 100644 --- a/troubleshooting/other-troubleshooting-tips/rancher-ha.html +++ b/troubleshooting/other-troubleshooting-tips/rancher-ha.html @@ -5,13 +5,13 @@ Rancher HA | Rancher Manager - +
    Version: v2.6

    Rancher HA

    The commands/steps listed on this page can be used to check your Rancher Kubernetes Installation.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml).

    Check Rancher pods​

    Rancher pods are deployed as a Deployment in the cattle-system namespace.

    Check if the pods are running on all nodes:

    kubectl -n cattle-system get pods -l app=rancher -o wide

    Example output:

    NAME                       READY   STATUS    RESTARTS   AGE   IP          NODE
    rancher-7dbd7875f7-n6t5t   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qbj5k   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qw7wb   1/1     Running   0          8m    x.x.x.x     x.x.x.x

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n cattle-system describe pods -l app=rancher

    Pod container logs​

    kubectl -n cattle-system logs -l app=rancher

    Namespace events​

    kubectl -n cattle-system get events

    Check ingress​

    Ingress should have the correct HOSTS (showing the configured FQDN) and ADDRESS (host address(es) it will be routed to).

    kubectl -n cattle-system get ingress

    Example output:

    NAME      HOSTS                    ADDRESS                   PORTS     AGE
    rancher   rancher.yourdomain.com   x.x.x.x,x.x.x.x,x.x.x.x   80, 443   2m

    Check ingress controller logs​

    When accessing your configured Rancher FQDN does not show you the UI, check the ingress controller logging to see what happens when you try to access Rancher:

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    Leader election​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the cattle-controllers ConfigMap (in this example, rancher-7dbd7875f7-qbj5k).

    kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0}
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/registered-clusters.html b/troubleshooting/other-troubleshooting-tips/registered-clusters.html index 8419add949a..7c764ef108c 100644 --- a/troubleshooting/other-troubleshooting-tips/registered-clusters.html +++ b/troubleshooting/other-troubleshooting-tips/registered-clusters.html @@ -5,13 +5,13 @@ Registered Clusters | Rancher Manager - +
    Version: v2.6

    Registered Clusters

    The commands/steps listed on this page can be used to check clusters that you are registering or that are registered in Rancher.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kubeconfig_from_imported_cluster.yml)

    Rancher agents​

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes is done through Rancher agents.

    If the cattle-cluster-agent cannot connect to the configured server-url, the cluster will remain in Pending state, showing Waiting for full cluster configuration.

    cattle-node-agent​

    note

    cattle-node-agents are only present in clusters created in Rancher with RKE.

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.html b/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.html index a572b314349..451b9ed8fdf 100644 --- a/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.html +++ b/troubleshooting/other-troubleshooting-tips/user-id-tracking-in-audit-logs.html @@ -5,7 +5,7 @@ User ID Tracking in Audit Logs | Rancher Manager - + @@ -14,7 +14,7 @@ To know this mapping, the cluster admins needed to have access to Rancher API, UI, and the local management cluster.

    Now with this feature, a downstream cluster admin should be able to look at the Kubernetes audit logs and know which specific external Identity Provider (IDP) user performed an action without needing to view anything in Rancher. If the audit logs are shipped off of the cluster, a user of the logging system should be able to identify the user in the external Identity Provider system. A Rancher Admin should now be able to view Rancher audit logs and follow through to the Kubernetes audit log by using the external Identity Provider username.

    Feature Description​

    • When Kubernetes Audit logs are enabled on the downstream cluster, in each event that is logged, the external Identity Provider's username is now logged for each request, at the "metadata" level.
    • When Rancher API Audit logs are enabled on the Rancher installation, the external Identity Provider's username is also logged now at the auditLog.level=1 for each request that hits the Rancher API server, including the login requests.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4.html b/v2.0-v2.4.html index de17f1632e4..015a5a92ce1 100644 --- a/v2.0-v2.4.html +++ b/v2.0-v2.4.html @@ -5,13 +5,13 @@ Rancher 2.0-2.4 | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher 2.0-2.4

    Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2.x exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.

    Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.

    Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.

    It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes a pipeline engine to help you automatically deploy and upgrade workloads.

    Rancher is a complete container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/backups/backup.html b/v2.0-v2.4/backups/backup.html index ce885636c0e..35c22ed5db6 100644 --- a/v2.0-v2.4/backups/backup.html +++ b/v2.0-v2.4/backups/backup.html @@ -5,13 +5,13 @@ Backup | Rancher Manager - +
    Version: v2.0-v2.4

    Backup

    This section contains information about how to create backups of your Rancher data and how to restore them in a disaster scenario.

    For information on backing up Rancher launched Kubernetes clusters, refer to this section.

    If you are looking to back up your Rancher launched Kubernetes cluster, please refer here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/backups/restore.html b/v2.0-v2.4/backups/restore.html index 59066ad6e1b..47e2129ab75 100644 --- a/v2.0-v2.4/backups/restore.html +++ b/v2.0-v2.4/backups/restore.html @@ -5,13 +5,13 @@ Restore | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/contribute-to-rancher.html b/v2.0-v2.4/contribute-to-rancher.html index abc73da0299..0a2005cde30 100644 --- a/v2.0-v2.4/contribute-to-rancher.html +++ b/v2.0-v2.4/contribute-to-rancher.html @@ -5,14 +5,14 @@ Contributing to Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    Contributing to Rancher

    This section explains the repositories used for Rancher, how to build the repositories, and what information to include when you file an issue.

    For more detailed information on how to contribute to the development of Rancher projects, refer to the Rancher Developer Wiki. The wiki has resources on many topics, including the following:

    • How to set up the Rancher development environment and run tests
    • The typical flow of an issue through the development lifecycle
    • Coding guidelines and development best practices
    • Debugging and troubleshooting
    • Developing the Rancher API

    On the Rancher Users Slack, the channel for developers is #developer.

    Repositories​

    All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher.

    RepositoryURLDescription
    Rancherhttps://github.com/rancher/rancherThis repository is the main source code for Rancher 2.x.
    Typeshttps://github.com/rancher/typesThis repository is the repository that has all the API types for Rancher 2.x.
    API Frameworkhttps://github.com/rancher/normanThis repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources.
    User Interfacehttps://github.com/rancher/uiThis repository is the source of the UI.
    (Rancher) Docker Machinehttps://github.com/rancher/machineThis repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the docker/machine repository.
    machine-packagehttps://github.com/rancher/machine-packageThis repository is used to build the Rancher Docker Machine binary.
    kontainer-enginehttps://github.com/rancher/kontainer-engineThis repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters.
    RKE repositoryhttps://github.com/rancher/rkeThis repository is the source of Rancher Kubernetes Engine, the tool to provision Kubernetes clusters on any machine.
    CLIhttps://github.com/rancher/cliThis repository is the source code for the Rancher CLI used in Rancher 2.x.
    (Rancher) Helm repositoryhttps://github.com/rancher/helmThis repository is the source of the packaged Helm binary. This is a fork of the helm/helm repository.
    Telemetry repositoryhttps://github.com/rancher/telemetryThis repository is the source for the Telemetry binary.
    loglevel repositoryhttps://github.com/rancher/loglevelThis repository is the source of the loglevel binary, used to dynamically change log levels.

    To see all libraries/projects used in Rancher, see the go.mod file in the rancher/rancher repository.

    Rancher diagram

    Rancher components used for provisioning/managing Kubernetes clusters.

    Building​

    Every repository should have a Makefile and can be built using the make command. The make targets are based on the scripts in the /scripts directory in the repository, and each target will use Dapper to run the target in an isolated environment. The Dockerfile.dapper will be used for this process, and includes all the necessary build tooling needed.

    The default target is ci, and will run ./scripts/validate, ./scripts/build, ./scripts/test and ./scripts/package. The resulting binaries of the build will be in ./build/bin and are usually also packaged in a Docker image.

    Bugs, Issues or Questions​

    If you find any bugs or are having any trouble, please search the reported issue as someone may have experienced the same issue or we are actively working on a solution.

    If you can't find anything related to your issue, contact us by filing an issue. Though we have many repositories related to Rancher, we want the bugs filed in the Rancher repository so we won't miss them! If you want to ask a question or ask fellow users about an use case, we suggest creating a post on the Rancher Forums.

    Checklist for Filing Issues​

    Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue.

    Note: For large amounts of data, please use GitHub Gist or similar and link the created resource in the issue. Important: Please remove any sensitive data as it will be publicly viewable.

    • Resources: Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below:

      • Hosts: What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce
      • Operating System: What operating system are you using? Providing specifics helps here like the output of cat /etc/os-release for exact OS release and uname -r for exact kernel used
      • Docker: What Docker version are you using, how did you install it? Most of the details of Docker can be found by supplying output of docker version and docker info
      • Environment: Are you in a proxy environment, are you using recognized CA/self signed certificates, are you using an external loadbalancer
      • Rancher: What version of Rancher are you using, this can be found on the bottom left of the UI or be retrieved from the image tag you are running on the host
      • Clusters: What kind of cluster did you create, how did you create it, what did you specify when you were creating it

    • Steps to reproduce the issue: Provide as much detail on how you got into the reported situation. This helps the person to reproduce the situation you are in.

      • Provide manual steps or automation scripts used to get from a newly created setup to the situation you reported.

    • Logs: Provide data/logs from the used resources.

      • Rancher

        • Docker install

          docker logs \
          --timestamps \
          $(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }')

        • Kubernetes install using kubectl

          Note: Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

          kubectl -n cattle-system \
          logs \
          -l app=rancher \
          --timestamps=true

        • Docker install using docker on each of the nodes in the RKE cluster

          docker logs \
          --timestamps \
          $(docker ps | grep -E "rancher/rancher@|rancher_rancher" | awk '{ print $1 }')

        • Kubernetes Install with RKE Add-On

          Note: Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

          kubectl -n cattle-system \
          logs \
          --timestamps=true \
          -f $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name="cattle-server") | .metadata.name')

      • System logging (these might not all exist, depending on operating system)

        • /var/log/messages
        • /var/log/syslog
        • /var/log/kern.log

      • Docker daemon logging (these might not all exist, depending on operating system)

        • /var/log/docker.log

    • Metrics: If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of top, free -m, df which shows processes/memory/disk usage.

    Docs​

    If you have any updates to our documentation, please make any pull request to our docs repo.

    • Rancher 2.x Docs repository: This repo is where all the docs for Rancher 2.x are located. They are located in the content folder in the repo.

    • Rancher 1.x Docs repository: This repo is where all the docs for Rancher 1.x are located. They are located in the rancher folder in the repo.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations.html b/v2.0-v2.4/explanations.html index 93e4b095e0d..c29bbb6c9e8 100644 --- a/v2.0-v2.4/explanations.html +++ b/v2.0-v2.4/explanations.html @@ -5,13 +5,13 @@ Explanations | Rancher Manager - +
    Version: v2.0-v2.4

    Explanations

    Explanatory docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html b/v2.0-v2.4/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html index 72078e80234..d9b77899747 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html @@ -5,13 +5,13 @@ Skipped and Not Applicable Tests | Rancher Manager - +
    Version: v2.0-v2.4

    Skipped and Not Applicable Tests

    This section lists the tests that are skipped in the permissive test profile for RKE.

    All the tests that are skipped and not applicable on this page will be counted as Not Applicable in the generated report. The skipped test count will only mention the user-defined skipped tests. This allows user-skipped tests to be distinguished from the tests that are skipped by default in the RKE permissive test profile.

    CIS Benchmark v1.5​

    CIS Benchmark v1.5 Skipped Tests​

    NumberDescriptionReason for Skipping
    1.1.12Ensure that the etcd data directory ownership is set to etcd:etcd (Scored)A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership.
    1.2.6Ensure that the --kubelet-certificate-authority argument is set as appropriate (Scored)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
    1.2.16Ensure that the admission control plugin PodSecurityPolicy is set (Scored)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.2.33Ensure that the --encryption-provider-config argument is set as appropriate (Not Scored)Enabling encryption changes how data can be recovered as data is encrypted.
    1.2.34Ensure that encryption providers are appropriately configured (Not Scored)Enabling encryption changes how data can be recovered as data is encrypted.
    4.2.6Ensure that the --protect-kernel-defaults argument is set to true (Scored)System level configurations are required before provisioning the cluster in order for this argument to be set to true.
    4.2.10Ensure that the--tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
    5.1.5Ensure that default service accounts are not actively used. (Scored)Kubernetes provides default service accounts to be used.
    5.2.2Minimize the admission of containers wishing to share the host process ID namespace (Scored)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.3Minimize the admission of containers wishing to share the host IPC namespace (Scored)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.4Minimize the admission of containers wishing to share the host network namespace (Scored)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.5Minimize the admission of containers with allowPrivilegeEscalation (Scored)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.3.2Ensure that all Namespaces have Network Policies defined (Scored)Enabling Network Policies can prevent certain applications from communicating with each other.
    5.6.4The default namespace should not be used (Scored)Kubernetes provides a default namespace.

    CIS Benchmark v1.5 Not Applicable Tests​

    NumberDescriptionReason for being not applicable
    1.1.1Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
    1.1.2Ensure that the API server pod specification file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
    1.1.3Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.4Ensure that the controller manager pod specification file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.5Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.6Ensure that the scheduler pod specification file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.7Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
    1.1.8Ensure that the etcd pod specification file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
    1.1.13Ensure that the admin.conf file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    1.1.14Ensure that the admin.conf file ownership is set to root:root (Scored)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    1.1.15Ensure that the scheduler.conf file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.16Ensure that the scheduler.conf file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.17Ensure that the controller-manager.conf file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.18Ensure that the controller-manager.conf file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.3.6Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)Clusters provisioned by RKE handles certificate rotation directly through RKE.
    4.1.1Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
    4.1.2Ensure that the kubelet service file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
    4.1.9Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Scored)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
    4.1.10Ensure that the kubelet configuration file ownership is set to root:root (Scored)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
    4.2.12Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)Clusters provisioned by RKE handles certificate rotation directly through RKE.

    CIS Benchmark v1.4​

    The skipped and not applicable tests for CIS Benchmark v1.4 are as follows:

    CIS Benchmark v1.4 Skipped Tests​

    NumberDescriptionReason for Skipping
    1.1.11"Ensure that the admission control plugin AlwaysPullImages is set (Scored)"Enabling AlwaysPullImages can use significant bandwidth.
    1.1.21"Ensure that the --kubelet-certificate-authority argument is set as appropriate (Scored)"When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
    1.1.24"Ensure that the admission control plugin PodSecurityPolicy is set (Scored)"Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.1.34"Ensure that the --encryption-provider-config argument is set as appropriate (Scored)"Enabling encryption changes how data can be recovered as data is encrypted.
    1.1.35"Ensure that the encryption provider is set to aescbc (Scored)"Enabling encryption changes how data can be recovered as data is encrypted.
    1.1.36"Ensure that the admission control plugin EventRateLimit is set (Scored)"EventRateLimit needs to be tuned depending on the cluster.
    1.2.2"Ensure that the --address argument is set to 127.0.0.1 (Scored)"Adding this argument prevents Rancher's monitoring tool to collect metrics on the scheduler.
    1.3.7"Ensure that the --address argument is set to 127.0.0.1 (Scored)"Adding this argument prevents Rancher's monitoring tool to collect metrics on the controller manager.
    1.4.12"Ensure that the etcd data directory ownership is set to etcd:etcd (Scored)"A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership.
    1.7.2"Do not admit containers wishing to share the host process ID namespace (Scored)"Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.7.3"Do not admit containers wishing to share the host IPC namespace (Scored)"Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.7.4"Do not admit containers wishing to share the host network namespace (Scored)"Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.7.5" Do not admit containers with allowPrivilegeEscalation (Scored)"Enabling Pod Security Policy can cause applications to unexpectedly fail.
    2.1.6"Ensure that the --protect-kernel-defaults argument is set to true (Scored)"System level configurations are required before provisioning the cluster in order for this argument to be set to true.
    2.1.10"Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)"When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.

    CIS Benchmark v1.4 Not Applicable Tests​

    NumberDescriptionReason for being not applicable
    1.1.9"Ensure that the --repair-malformed-updates argument is set to false (Scored)"The argument --repair-malformed-updates has been removed as of Kubernetes version 1.14
    1.3.6"Ensure that the RotateKubeletServerCertificate argument is set to true"Cluster provisioned by RKE handles certificate rotation directly through RKE.
    1.4.1"Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver.
    1.4.2"Ensure that the API server pod specification file ownership is set to root:root (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver.
    1.4.3"Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for controller-manager.
    1.4.4"Ensure that the controller manager pod specification file ownership is set to root:root (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for controller-manager.
    1.4.5"Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for scheduler.
    1.4.6"Ensure that the scheduler pod specification file ownership is set to root:root (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for scheduler.
    1.4.7"Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for etcd.
    1.4.8"Ensure that the etcd pod specification file ownership is set to root:root (Scored)"Cluster provisioned by RKE doesn't require or maintain a configuration file for etcd.
    1.4.13"Ensure that the admin.conf file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    1.4.14"Ensure that the admin.conf file ownership is set to root:root (Scored)"Cluster provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    2.1.8"Ensure that the --hostname-override argument is not set (Scored)"Clusters provisioned by RKE clusters and most cloud providers require hostnames.
    2.1.12"Ensure that the --rotate-certificates argument is not set to false (Scored)"Cluster provisioned by RKE handles certificate rotation directly through RKE.
    2.1.13"Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)"Cluster provisioned by RKE handles certificate rotation directly through RKE.
    2.2.3"Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)"Cluster provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service.
    2.2.4"Ensure that the kubelet service file ownership is set to root:root (Scored)"Cluster provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service.
    2.2.9"Ensure that the kubelet configuration file ownership is set to root:root (Scored)"RKE doesn’t require or maintain a configuration file for the kubelet.
    2.2.10"Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Scored)"RKE doesn’t require or maintain a configuration file for the kubelet.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.html index 997d1c1b392..fe1f8da6a32 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-alerts/default-alerts.html @@ -5,13 +5,13 @@ Default Alerts for Cluster Monitoring | Rancher Manager - +
    Version: v2.0-v2.4

    Default Alerts for Cluster Monitoring

    When you create a cluster, some alert rules are predefined. These alerts notify you about signs that the cluster could be unhealthy. You can receive these alerts if you configure a notifier for them.

    Several of the alerts use Prometheus expressions as the metric that triggers the alert. For more information on how expressions work, you can refer to the Rancher documentation about Prometheus expressions or the Prometheus documentation about querying metrics.

    Alerts for etcd

    Etcd is the key-value store that contains the state of the Kubernetes cluster. Rancher provides default alerts if the built-in monitoring detects a potential problem with etcd. You don't have to enable monitoring to receive these alerts.

    A leader is the node that handles all client requests that need cluster consensus. For more information, you can refer to this explanation of how etcd works.

    The leader of the cluster can change in response to certain events. It is normal for the leader to change, but too many changes can indicate a problem with the network or a high CPU load. With longer latencies, the default etcd configuration may cause frequent heartbeat timeouts, which trigger a new leader election.

    AlertExplanation
    A high number of leader changes within the etcd cluster are happeningA warning alert is triggered when the leader changes more than three times in one hour.
    Database usage close to the quota 500MA warning alert is triggered when the size of etcd exceeds 500M.
    Etcd is unavailableA critical alert is triggered when etcd becomes unavailable.
    Etcd member has no leaderA critical alert is triggered when the etcd cluster does not have a leader for at least three minutes.

    Alerts for Kubernetes Components

    Rancher provides alerts when core Kubernetes system components become unhealthy.

    Controllers update Kubernetes resources based on changes in etcd. The controller manager monitors the cluster desired state through the Kubernetes API server and makes the necessary changes to the current state to reach the desired state.

    The scheduler service is a core component of Kubernetes. It is responsible for scheduling cluster workloads to nodes, based on various configurations, metrics, resource requirements and workload-specific requirements.

    AlertExplanation
    Controller Manager is unavailableA critical warning is triggered when the cluster’s controller-manager becomes unavailable.
    Scheduler is unavailableA critical warning is triggered when the cluster’s scheduler becomes unavailable.

    Alerts for Events

    Kubernetes events are objects that provide insight into what is happening inside a cluster, such as what decisions were made by the scheduler or why some pods were evicted from the node. In the Rancher UI, from the project view, you can see events for each workload.

    AlertExplanation
    Get warning deployment eventA warning alert is triggered when a warning event happens on a deployment.

    Alerts for Nodes

    Alerts can be triggered based on node metrics. Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines.

    AlertExplanation
    High CPU loadA warning alert is triggered if the node uses more than 100 percent of the node’s available CPU seconds for at least three minutes.
    High node memory utilizationA warning alert is triggered if the node uses more than 80 percent of its available memory for at least three minutes.
    Node disk is running full within 24 hoursA critical alert is triggered if the disk space on the node is expected to run out in the next 24 hours based on the disk growth over the last 6 hours.

    Project-level Alerts

    When you enable monitoring for the project, some project-level alerts are provided. For details, refer to the section on project-level alerts.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/elasticsearch.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/elasticsearch.html index e8f7d39b19e..8ca006f8fc3 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/elasticsearch.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/elasticsearch.html @@ -5,13 +5,13 @@ Elasticsearch | Rancher Manager - +
    Version: v2.0-v2.4

    Elasticsearch

    If your organization uses Elasticsearch, either on premise or in the cloud, you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Elasticsearch deployment to view logs.

    Prerequisites: Configure an Elasticsearch deployment.

    Elasticsearch Deployment Configuration​

    1. In the Endpoint field, enter the IP address and port of your Elasticsearch instance. You can find this information from the dashboard of your Elasticsearch deployment.

      • Elasticsearch usually uses port 9200 for HTTP and 9243 for HTTPS.

    2. If you are using X-Pack Security, enter your Elasticsearch Username and Password for authentication.

    3. Enter an Index Pattern.

    SSL Configuration​

    If your instance of Elasticsearch uses SSL, your Endpoint will need to begin with https://. With the correct endpoint, the SSL Configuration form is enabled and ready to be completed.

    1. Provide the Client Private Key and Client Certificate. You can either copy and paste them or upload them by using the Read from a file button.

      • You can use either a self-signed certificate or one provided by a certificate authority.

      • You can generate a self-signed certificate using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

    2. Enter your Client Key Password.

    3. Enter your SSL Version. The default version is TLSv1_2.

    4. Select whether or not you want to verify your SSL.

      • If you are using a self-signed certificate, select Enabled - Input trusted server certificate, provide the CA Certificate PEM. You can copy and paste the certificate or upload it using the Read from a file button.
      • If you are using a certificate from a certificate authority, select Enabled - Input trusted server certificate. You do not need to provide a CA Certificate PEM.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/fluentd.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/fluentd.html index e2da7aa447b..4331e0c7a93 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/fluentd.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/fluentd.html @@ -5,13 +5,13 @@ Fluentd | Rancher Manager - +
    Version: v2.0-v2.4

    Fluentd

    If your organization uses Fluentd, you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Fluentd server to view logs.

    Prerequisites: Configure Fluentd input forward to receive the event stream.

    See Fluentd Documentation for details.

    Fluentd Configuration​

    You can add multiple Fluentd Servers. If you want to add additional Fluentd servers, click Add Fluentd Server. For each Fluentd server, complete the configuration information:

    1. In the Endpoint field, enter the address and port of your Fluentd instance, e.g. http://Fluentd-server:24224.

    2. Enter the Shared Key if your Fluentd Server is using a shared key for authentication.

    3. Enter the Username and Password if your Fluentd Server is using username and password for authentication.

    4. Optional: Enter the Hostname of the Fluentd server.

    5. Enter the load balancing Weight of the Fluentd server. If the weight of one server is 20 and the other server is 30, events will be sent in a 2:3 ratio. If you do not enter a weight, the default weight is 60.

    6. If this server is a standby server, check Use as Standby Only. Standby servers are used when all other servers are not available.

    After adding all the Fluentd servers, you have the option to select Enable Gzip Compression. By default, this is enabled because the transferred payload size will be reduced.

    SSL Configuration​

    If your Fluentd servers are using TLS, you need to select Use TLS. If you are using a self-signed certificate, provide the CA Certificate PEM. You can copy and paste the certificate or upload it using the Read from a file button.

    Note: Fluentd does not support self-signed certificates when client authentication is enabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/kafka.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/kafka.html index d5eb3e0fe82..2f997b551d9 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/kafka.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/kafka.html @@ -5,13 +5,13 @@ Kafka | Rancher Manager - +
    Version: v2.0-v2.4

    Kafka

    If your organization uses Kafka, you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Kafka server to view logs.

    Prerequisite: You must have a Kafka server configured.

    Kafka Server Configuration​

    1. Select the type of Endpoint your Kafka server is using:
    • Zookeeper: Enter the IP address and port. By default, Zookeeper uses port 2181. Please note that a Zookeeper endpoint cannot enable TLS.
    • Broker: Click on Add Endpoint. For each Kafka broker, enter the IP address and port. By default, Kafka brokers use port 9092.
    1. In the Topic field, enter the name of a Kafka topic that your Kubernetes cluster submits logs to.

    Broker Endpoint Type​

    SSL Configuration​

    If your Kafka cluster is using SSL for the Broker, you need to complete the SSL Configuration form.

    1. Provide the Client Private Key and Client Certificate. You can either copy and paste them or upload them by using the Read from a file button.

    2. Provide the CA Certificate PEM. You can either copy and paste the certificate or upload it using the Read from a file button.

    Note: Kafka does not support self-signed certificates when client authentication is enabled.

    SASL configuration​

    If your Kafka cluster is using SASL authentication for the Broker, you need to complete the SASL Configuration form.

    1. Enter the SASL Username and Password.

    2. Select the SASL Type that your Kafka cluster is using.

      • If your Kafka is using Plain, please ensure your Kafka cluster is using SSL.

      • If your Kafka is using Scram, you need to select which Scram Mechanism Kafka is using.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/splunk.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/splunk.html index 2d39d8846e3..82e20d81d7e 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/splunk.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/splunk.html @@ -5,7 +5,7 @@ Splunk | Rancher Manager - + @@ -14,7 +14,7 @@ View Logs

  • To view the actual logs, click on the source that you declared earlier. View Logs

    • Troubleshooting​

    You can use curl to see if HEC is listening for HTTP event data.

    $ curl http://splunk-server:8088/services/collector/event \
        -H 'Authorization: Splunk 8da70994-b1b0-4a79-b154-bfaae8f93432' \
        -d '{"event": "hello world"}'

    If Splunk is configured correctly, you should receive json data returning success code 0. You should be able to send logging data to HEC.

    If you received an error, check your configuration in Splunk and Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/syslog.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/syslog.html index d654301c0f7..305266140b5 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/syslog.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-logging/syslog.html @@ -5,13 +5,13 @@ Syslog | Rancher Manager - +
    Version: v2.0-v2.4

    Syslog

    If your organization uses Syslog, you can configure Rancher to send it Kubernetes logs. Afterwards, you can log into your Syslog server to view logs.

    Prerequisite: You must have a Syslog server configured.

    If you are using rsyslog, please make sure your rsyslog authentication mode is x509/name.

    Syslog Server Configuration​

    1. In the Endpoint field, enter the IP address and port for your Syslog server. Additionally, in the dropdown, select the protocol that your Syslog server uses.

    2. In the Program field, enter the name of the application sending logs to your Syslog server, e.g. Rancher.

    3. If you are using a cloud logging service, e.g. Sumologic, enter a Token that authenticates with your Syslog server. You will need to create this token in the cloud logging service.

    4. Select a Log Severity for events that are logged to the Syslog server. For more information on each severity level, see the Syslog protocol documentation.

      • By specifying a Log Severity does not mean that will act as a filtering mechanism for logs. To do that you should use a parser on the Syslog server.

    Encryption Configuration​

    If your Syslog server is using TCP protocol and uses TLS, you need to select Use TLS and complete the Encryption Configuration form.

    1. Provide the Client Private Key and Client Certificate. You can either copy and paste them or upload them by using the Read from a file button.

      • You can use either a self-signed certificate or one provided by a certificate authority.

      • You can generate a self-signed certificate using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

    2. Select whether or not you want to verify your SSL.

      • If you are using a self-signed certificate, select Enabled - Input trusted server certificate, provide the CA Certificate PEM. You can copy and paste the certificate or upload it using the Read from a file button.
      • If you are using a certificate from a certificate authority, select Enabled - Input trusted server certificate. You do not need to provide a CA Certificate PEM.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-metrics.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-metrics.html index bda67054907..8f482c21f19 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-metrics.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/cluster-metrics.html @@ -5,13 +5,13 @@ Cluster Metrics | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Metrics

    Available as of v2.2.0

    Cluster metrics display the hardware utilization for all nodes in your cluster, regardless of its role. They give you a global monitoring insight into the cluster.

    Some of the biggest metrics to look out for:

    • CPU Utilization

      High load either indicates that your cluster is running efficiently or that you're running out of CPU resources.

    • Disk Utilization

      Be on the lookout for increased read and write rates on nodes nearing their disk capacity. This advice is especially true for etcd nodes, as running out of storage on an etcd node leads to cluster failure.

    • Memory Utilization

      Deltas in memory utilization usually indicate a memory leak.

    • Load Average

      Generally, you want your load average to match your number of logical CPUs for the cluster. For example, if your cluster has 8 logical CPUs, the ideal load average would be 8 as well. If you load average is well under the number of logical CPUs for the cluster, you may want to reduce cluster resources. On the other hand, if your average is over 8, your cluster may need more resources.

    Finding Node Metrics​

    1. From the Global view, navigate to the cluster that you want to view metrics.

    2. Select Nodes in the navigation bar.

    3. Select a specific node and click on its name.

    4. Click on Node Metrics.

    Get expressions for Cluster Metrics

    Etcd Metrics​

    Note: Only supported for Rancher launched Kubernetes clusters.

    Etcd metrics display the operations of the etcd database on each of your cluster nodes. After establishing a baseline of normal etcd operational metrics, observe them for abnormal deltas between metric refreshes, which indicate potential issues with etcd. Always address etcd issues immediately!

    You should also pay attention to the text at the top of the etcd metrics, which displays leader election statistics. This text indicates if etcd currently has a leader, which is the etcd instance that coordinates the other etcd instances in your cluster. A large increase in leader changes implies etcd is unstable. If you notice a change in leader election statistics, you should investigate them for issues.

    Some of the biggest metrics to look out for:

    • Etcd has a leader

      etcd is usually deployed on multiple nodes and elects a leader to coordinate its operations. If etcd does not have a leader, its operations are not being coordinated.

    • Number of leader changes

      If this statistic suddenly grows, it usually indicates network communication issues that constantly force the cluster to elect a new leader.

    Get expressions for Etcd Metrics

    Kubernetes Components Metrics​

    Kubernetes components metrics display data about the cluster's individual Kubernetes components. Primarily, it displays information about connections and latency for each component: the API server, controller manager, scheduler, and ingress controller.

    Note: The metrics for the controller manager, scheduler and ingress controller are only supported for Rancher launched Kubernetes clusters.

    When analyzing Kubernetes component metrics, don't be concerned about any single standalone metric in the charts and graphs that display. Rather, you should establish a baseline for metrics considered normal following a period of observation, e.g. the range of values that your components usually operate within and are considered normal. After you establish this baseline, be on the lookout for large deltas in the charts and graphs, as these big changes usually indicate a problem that you need to investigate.

    Some of the more important component metrics to monitor are:

    • API Server Request Latency

      Increasing API response times indicate there's a generalized problem that requires investigation.

    • API Server Request Rate

      Rising API request rates usually coincide with increased API response times. Increased request rates also indicate a generalized problem requiring investigation.

    • Scheduler Preemption Attempts

      If you see a spike in scheduler preemptions, it's an indication that you're running out of hardware resources, as Kubernetes is recognizing it doesn't have enough resources to run all your pods and is prioritizing the more important ones.

    • Scheduling Failed Pods

      Failed pods can have a variety of causes, such as unbound persistent volume claims, exhausted hardware resources, non-responsive nodes, etc.

    • Ingress Controller Request Process Time

      How fast ingress is routing connections to your cluster services.

    Get expressions for Kubernetes Component Metrics

    Rancher Logging Metrics​

    Although the Dashboard for a cluster primarily displays data sourced from Prometheus, it also displays information for cluster logging, provided that you have configured Rancher to use a logging service.

    Get expressions for Rancher Logging Metrics

    Finding Workload Metrics​

    Workload metrics display the hardware utilization for a Kubernetes workload. You can also view metrics for deployments, stateful sets and so on.

    1. From the Global view, navigate to the project that you want to view workload metrics.

    2. From the main navigation bar, choose Resources > Workloads. In versions before v2.3.0, choose Workloads on the main navigation bar.

    3. Select a specific workload and click on its name.

    4. In the Pods section, select a specific pod and click on its name.

      • View the Pod Metrics: Click on Pod Metrics.
      • View the Container Metrics: In the Containers section, select a specific container and click on its name. Click on Container Metrics.

    Get expressions for Workload Metrics

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/custom-metrics.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/custom-metrics.html index 36bc07f7228..db2b9aa957b 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/custom-metrics.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/custom-metrics.html @@ -5,7 +5,7 @@ Prometheus Custom Metrics Adapter | Rancher Manager - + @@ -76,7 +76,7 @@ fields:

    • LabelValuesByName: a map mapping the labels and GroupBy fields. The other two are for advanced usage.

      The query is expected to return one value for each object requested. The adapter will use the labels on the returned series to associate a given series back to its corresponding object.

      For example:

      # convert cumulative cAdvisor metrics into rates calculated over 2 minutes
      metricsQuery: "sum(rate(<<.Series>>{<<.LabelMatchers>>,container_name!="POD"}[2m])) by (<<.GroupBy>>)"
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.html index f3b58b6495e..17927383645 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/expression.html @@ -5,13 +5,13 @@ Prometheus Expressions | Rancher Manager - +
      Version: v2.0-v2.4

      Prometheus Expressions

      The PromQL expressions in this doc can be used to configure alerts.

      Before expressions can be used in alerts, monitoring must be enabled. For more information, refer to the documentation on enabling monitoring at the cluster level or at the project level.

      For more information about querying Prometheus, refer to the official Prometheus documentation.

      Cluster Metrics

      Cluster CPU Utilization​

      CatalogExpression
      Detail1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))
      Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))

      Cluster Load Average​

      CatalogExpression
      Detail
      load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
      load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
      load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
      Summary
      load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})
      load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})
      load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})

      Cluster Memory Utilization​

      CatalogExpression
      Detail1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)
      Summary1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)

      Cluster Disk Utilization​

      CatalogExpression
      Detail(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)
      Summary(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})

      Cluster Disk I/O​

      CatalogExpression
      Detail
      readsum(rate(node_disk_read_bytes_total[5m])) by (instance)
      writtensum(rate(node_disk_written_bytes_total[5m])) by (instance)
      Summary
      readsum(rate(node_disk_read_bytes_total[5m]))
      writtensum(rate(node_disk_written_bytes_total[5m]))

      Cluster Network Packets​

      CatalogExpression
      Detail
      receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      Summary
      receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

      Cluster Network I/O​

      CatalogExpression
      Detail
      receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
      Summary
      receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
      transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

      Node Metrics

      Node CPU Utilization​

      CatalogExpression
      Detailavg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)
      Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))

      Node Load Average​

      CatalogExpression
      Detail
      load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
      load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
      load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
      Summary
      load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
      load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
      load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})

      Node Memory Utilization​

      CatalogExpression
      Detail1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})
      Summary1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})

      Node Disk Utilization​

      CatalogExpression
      Detail(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)
      Summary(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})

      Node Disk I/O​

      CatalogExpression
      Detail
      readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
      writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))
      Summary
      readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
      writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))

      Node Network Packets​

      CatalogExpression
      Detail
      receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      Summary
      receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

      Node Network I/O​

      CatalogExpression
      Detail
      receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
      Summary
      receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
      transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

      Etcd Metrics

      Etcd Has a Leader​

      max(etcd_server_has_leader)

      Number of Times the Leader Changes​

      max(etcd_server_leader_changes_seen_total)

      Number of Failed Proposals​

      sum(etcd_server_proposals_failed_total)

      GRPC Client Traffic​

      CatalogExpression
      Detail
      insum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)
      outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)
      Summary
      insum(rate(etcd_network_client_grpc_received_bytes_total[5m]))
      outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))

      Peer Traffic​

      CatalogExpression
      Detail
      insum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)
      outsum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)
      Summary
      insum(rate(etcd_network_peer_received_bytes_total[5m]))
      outsum(rate(etcd_network_peer_sent_bytes_total[5m]))

      DB Size​

      CatalogExpression
      Detailsum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)
      Summarysum(etcd_debugging_mvcc_db_total_size_in_bytes)

      Active Streams​

      CatalogExpression
      Detail
      lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)
      watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)
      Summary
      lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})
      watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})

      Raft Proposals​

      CatalogExpression
      Detail
      appliedsum(increase(etcd_server_proposals_applied_total[5m])) by (instance)
      committedsum(increase(etcd_server_proposals_committed_total[5m])) by (instance)
      pendingsum(increase(etcd_server_proposals_pending[5m])) by (instance)
      failedsum(increase(etcd_server_proposals_failed_total[5m])) by (instance)
      Summary
      appliedsum(increase(etcd_server_proposals_applied_total[5m]))
      committedsum(increase(etcd_server_proposals_committed_total[5m]))
      pendingsum(increase(etcd_server_proposals_pending[5m]))
      failedsum(increase(etcd_server_proposals_failed_total[5m]))

      RPC Rate​

      CatalogExpression
      Detail
      totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)
      failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)
      Summary
      totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))
      failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))

      Disk Operations​

      CatalogExpression
      Detail
      commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)
      fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)
      Summary
      commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))
      fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))

      Disk Sync Duration​

      CatalogExpression
      Detail
      walhistogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))
      dbhistogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))
      Summary
      walsum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))
      dbsum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))

      Kubernetes Components Metrics

      API Server Request Latency​

      CatalogExpression
      Detailavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06
      Summaryavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06

      API Server Request Rate​

      CatalogExpression
      Detailsum(rate(apiserver_request_count[5m])) by (instance, code)
      Summarysum(rate(apiserver_request_count[5m])) by (instance)

      Scheduling Failed Pods​

      CatalogExpression
      Detailsum(kube_pod_status_scheduled{condition="false"})
      Summarysum(kube_pod_status_scheduled{condition="false"})

      Controller Manager Queue Depth​

      CatalogExpression
      Detail
      volumessum(volumes_depth) by instance
      deploymentsum(deployment_depth) by instance
      replicasetsum(replicaset_depth) by instance
      servicesum(service_depth) by instance
      serviceaccountsum(serviceaccount_depth) by instance
      endpointsum(endpoint_depth) by instance
      daemonsetsum(daemonset_depth) by instance
      statefulsetsum(statefulset_depth) by instance
      replicationmanagersum(replicationmanager_depth) by instance
      Summary
      volumessum(volumes_depth)
      deploymentsum(deployment_depth)
      replicasetsum(replicaset_depth)
      servicesum(service_depth)
      serviceaccountsum(serviceaccount_depth)
      endpointsum(endpoint_depth)
      daemonsetsum(daemonset_depth)
      statefulsetsum(statefulset_depth)
      replicationmanagersum(replicationmanager_depth)

      Scheduler E2E Scheduling Latency​

      CatalogExpression
      Detailhistogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06
      Summarysum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)

      Scheduler Preemption Attempts​

      CatalogExpression
      Detailsum(rate(scheduler_total_preemption_attempts[5m])) by (instance)
      Summarysum(rate(scheduler_total_preemption_attempts[5m]))

      Ingress Controller Connections​

      CatalogExpression
      Detail
      readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)
      waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)
      writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)
      acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)
      activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)
      handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)
      Summary
      readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"})
      waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"})
      writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"})
      acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))
      activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))
      handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))

      Ingress Controller Request Process Time​

      CatalogExpression
      Detailtopk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))
      Summarytopk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))

      Rancher Logging Metrics

      Fluentd Buffer Queue Rate​

      CatalogExpression
      Detailsum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)
      Summarysum(rate(fluentd_output_status_buffer_queue_length[5m]))

      Fluentd Input Rate​

      CatalogExpression
      Detailsum(rate(fluentd_input_status_num_records_total[5m])) by (instance)
      Summarysum(rate(fluentd_input_status_num_records_total[5m]))

      Fluentd Output Errors Rate​

      CatalogExpression
      Detailsum(rate(fluentd_output_status_num_errors[5m])) by (type)
      Summarysum(rate(fluentd_output_status_num_errors[5m]))

      Fluentd Output Rate​

      CatalogExpression
      Detailsum(rate(fluentd_output_status_num_records_total[5m])) by (instance)
      Summarysum(rate(fluentd_output_status_num_records_total[5m]))

      Workload Metrics

      Workload CPU Utilization​

      CatalogExpression
      Detail
      cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      Summary
      cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

      Workload Memory Utilization​

      CatalogExpression
      Detailsum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)
      Summarysum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})

      Workload Network Packets​

      CatalogExpression
      Detail
      receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      Summary
      receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

      Workload Network I/O​

      CatalogExpression
      Detail
      receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      Summary
      receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

      Workload Disk I/O​

      CatalogExpression
      Detail
      readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
      Summary
      readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
      writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

      Pod Metrics

      Pod CPU Utilization​

      CatalogExpression
      Detail
      cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
      usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
      system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
      user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
      Summary
      cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
      usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
      system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
      user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))

      Pod Memory Utilization​

      CatalogExpression
      Detailsum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)
      Summarysum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})

      Pod Network Packets​

      CatalogExpression
      Detail
      receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      Summary
      receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

      Pod Network I/O​

      CatalogExpression
      Detail
      receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      Summary
      receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

      Pod Disk I/O​

      CatalogExpression
      Detail
      readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
      writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
      Summary
      readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
      writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

      Container Metrics

      Container CPU Utilization​

      CatalogExpression
      cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
      usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
      system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
      user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))

      Container Memory Utilization​

      sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})

      Container Disk I/O​

      CatalogExpression
      readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
      writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.html index b6b6c0373cc..c8fc48b7bee 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/project-monitoring.html @@ -5,14 +5,14 @@ Project Monitoring | Rancher Manager - +
      Version: v2.0-v2.4

      Project Monitoring

      Available as of v2.2.4

      Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.

      Monitoring Scope​

      Using Prometheus, you can monitor Rancher at both the cluster level and project level. For each cluster and project that is enabled for monitoring, Rancher deploys a Prometheus server.

      • Cluster monitoring allows you to view the health of your Kubernetes cluster. Prometheus collects metrics from the cluster components below, which you can view in graphs and charts.

        • Kubernetes control plane
        • etcd database
        • All nodes (including workers)

      • Project monitoring allows you to view the state of pods running in a given project. Prometheus collects metrics from the project's deployed HTTP and TCP/UDP workloads.

      Permissions to Configure Project Monitoring​

      Only administrators, cluster owners or members, or project owners can configure project level monitoring. Project members can only view monitoring metrics.

      Enabling Project Monitoring​

      Prerequisite: Cluster monitoring must be enabled.

      1. Go to the project where monitoring should be enabled. Note: When cluster monitoring is enabled, monitoring is also enabled by default in the System project.

      2. Select Tools > Monitoring in the navigation bar.

      3. Select Enable to show the Prometheus configuration options. Enter in your desired configuration options.

      4. Click Save.

      Project-Level Monitoring Resource Requirements​

      ContainerCPU - RequestMem - RequestCPU - LimitMem - LimitConfigurable
      Prometheus750m750Mi1000m1000MiYes
      Grafana100m100Mi200m200MiNo

      Result: A single application,project-monitoring, is added as an application to the project. After the application is active, you can start viewing project metrics through the Rancher dashboard or directly from Grafana.

      The default username and password for the Grafana instance will be admin/admin. However, Grafana dashboards are served via the Rancher authentication proxy, so only users who are currently authenticated into the Rancher server have access to the Grafana dashboard.

      Project Metrics​

      Workload metrics are available for the project if monitoring is enabled at the cluster level and at the project level.

      You can monitor custom metrics from any exporters. You can also expose some custom endpoints on deployments without needing to configure Prometheus for your project.

      Example: A Redis application is deployed in the namespace redis-app in the project Datacenter. It is monitored via Redis exporter. After enabling project monitoring, you can edit the application to configure the Advanced Options -> Custom Metrics section. Enter the Container Port and Path and select the Protocol.

      To access a project-level Grafana instance,

      1. From the Global view, navigate to a cluster that has monitoring enabled.

      2. Go to a project that has monitoring enabled.

      3. From the project view, click Apps. In versions before v2.2.0, choose Catalog Apps on the main navigation bar.

      4. Go to the project-monitoring application.

      5. In the project-monitoring application, there are two /index.html links: one that leads to a Grafana instance and one that leads to a Prometheus instance. When you click the Grafana link, it will redirect you to a new webpage for Grafana, which shows metrics for the cluster.

      6. You will be signed in to the Grafana instance automatically. The default username is admin and the default password is admin. For security, we recommend that you log out of Grafana, log back in with the admin password, and change your password.

      Results: You will be logged into Grafana from the Grafana instance. After logging in, you can view the preset Grafana dashboards, which are imported via the Grafana provisioning mechanism, so you cannot modify them directly. For now, if you want to configure your own dashboards, clone the original and modify the new copy.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.html index 3bba8265819..f1a7423f12d 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/prometheus.html @@ -5,13 +5,13 @@ Prometheus Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      Prometheus Configuration

      Available as of v2.2.0

      While configuring monitoring at either the cluster level or project level, there are multiple options that can be configured.

      Basic Configuration

      OptionDescription
      Data RetentionHow long your Prometheus instance retains monitoring data scraped from Rancher objects before it's purged.
      Enable Node ExporterWhether or not to deploy the node exporter.
      Node Exporter Host PortThe host port on which data is exposed, i.e. data that Prometheus collects from your node hardware. Required if you have enabled the node exporter.
      Enable Persistent Storage for PrometheusWhether or not to configure storage for Prometheus so that metrics can be retained even if the Prometheus pod fails.
      Enable Persistent Storage for GrafanaWhether or not to configure storage for Grafana so that the Grafana dashboards and configuration can be retained even if the Grafana pod fails.
      Prometheus CPU LimitCPU resource limit for the Prometheus pod.
      Prometheus CPU ReservationCPU reservation for the Prometheus pod.
      Prometheus Memory LimitMemory resource limit for the Prometheus pod.
      Prometheus Memory ReservationMemory resource requests for the Prometheus pod.
      SelectorAbility to select the nodes in which Prometheus and Grafana pods are deployed to. To use this option, the nodes must have labels.

      Advanced Options

      Since monitoring is an application from the Rancher catalog, it can be configured like any other catalog application, by passing in values to Helm.

      Warning: Any modification to the application without understanding the entire application can lead to catastrophic errors.

      Prometheus RemoteRead and RemoteWrite​

      Available as of v2.4.0

      Prometheus RemoteRead and RemoteWrite can be configured as custom answers in the Advanced Options section.

      For more information on remote endpoints and storage, refer to the Prometheus documentation.

      The Prometheus operator documentation contains the full RemoteReadSpec and RemoteWriteSpec.

      An example configuration would be:

      VariableValue
      prometheus.remoteWrite[0].urlhttp://mytarget.com

      LivenessProbe and ReadinessProbe​

      Available as of v2.4.0

      Prometheus LivenessProbe and ReadinessProbe can be configured as custom answers in the Advanced Options section.

      The Kubernetes probe spec is here.

      Some example key-value pairs are:

      VariableValue
      prometheus.livenessProbe.timeoutSeconds60
      prometheus.readinessProbe.timeoutSeconds60

      Node Exporter

      The node exporter is a popular open source exporter, which exposes the metrics for hardware and *NIX kernels OS. It is designed to monitor the host system. However, there are still issues with namespaces when running it in a container, mostly around filesystem mount spaces. In order to monitor actual network metrics for the container network, the node exporter must be deployed with the hostNetwork mode.

      When configuring Prometheus and enabling the node exporter, enter a host port in the Node Exporter Host Port that will not produce port conflicts with existing applications. The host port chosen must be open to allow internal traffic between Prometheus and the Node Exporter.

      Warning: In order for Prometheus to collect the metrics of the node exporter, after enabling cluster monitoring, you must open the Node Exporter Host Port in the host firewall rules to allow intranet access. By default, 9796 is used as that host port.

      Persistent Storage

      Prerequisite: Configure one or more StorageClasses to use as persistent storage for your Prometheus or Grafana pod.

      By default, when you enable Prometheus for either a cluster or project, all monitoring data that Prometheus collects is stored on its own pod. With local storage, if the Prometheus or Grafana pods fail, all the data is lost. Rancher recommends configuring an external persistent storage to the cluster. With the external persistent storage, if the Prometheus or Grafana pods fail, the new pods can recover using data from the persistent storage.

      When enabling persistent storage for Prometheus or Grafana, specify the size of the persistent volume and select the StorageClass.

      Remote Storage

      Prerequisite: Need a remote storage endpoint to be available. The possible list of integrations is available here

      Using advanced options, remote storage integration for the Prometheus installation can be configured as follows:

      prometheus.remoteWrite[0].url = http://remote1/push
      prometheus.remoteWrite[0].remoteTimeout = 33s

      prometheus.remoteWrite[1].url = http://remote2/push


      prometheus.remoteRead[0].url = http://remote1/read
      prometheus.remoteRead[0].proxyUrl = http://proxy.url
      prometheus.remoteRead[0].bearerToken = token-value

      prometheus.remoteRead[1].url = http://remote2/read
      prometheus.remoteRead[1].remoteTimeout = 33s
      prometheus.remoteRead[1].readRecent = true

      Additional fields can be set up based on the ReadSpec and RemoteWriteSpec

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.html b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.html index 615f866bfaf..a266613e09a 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/cluster-monitoring/viewing-metrics.html @@ -5,13 +5,13 @@ Viewing Metrics | Rancher Manager - +
      Version: v2.0-v2.4

      Viewing Metrics

      Available as of v2.2.0

      After you've enabled monitoring at either the cluster level or project level, you will want to be start viewing the data being collected. There are multiple ways to view this data.

      Rancher Dashboard​

      Note: This is only available if you've enabled monitoring at the cluster level. Project specific analytics must be viewed using the project's Grafana instance.

      Rancher's dashboards are available at multiple locations:

      • Cluster Dashboard: From the Global view, navigate to the cluster.
      • Node Metrics: From the Global view, navigate to the cluster. Select Nodes. Find the individual node and click on its name. Click Node Metrics.
      • Workload Metrics: From the Global view, navigate to the project. From the main navigation bar, choose Resources > Workloads. (In versions before v2.3.0, choose Workloads on the main navigation bar.) Find the individual workload and click on its name. Click Workload Metrics.
      • Pod Metrics: From the Global view, navigate to the project. Select Workloads > Workloads. Find the individual workload and click on its name. Find the individual pod and click on its name. Click Pod Metrics.
      • Container Metrics: From the Global view, navigate to the project. From the main navigation bar, choose Resources > Workloads. (In versions before v2.3.0, choose Workloads on the main navigation bar.) Find the individual workload and click on its name. Find the individual pod and click on its name. Find the individual container and click on its name. Click Container Metrics.

      Prometheus metrics are displayed and are denoted with the Grafana icon. If you click on the icon, the metrics will open a new tab in Grafana.

      Within each Prometheus metrics widget, there are several ways to customize your view.

      • Toggle between two views:
        • Detail: Displays graphs and charts that let you view each event in a Prometheus time series
        • Summary Displays events in a Prometheus time series that are outside the norm.
      • Change the range of the time series that you're viewing to see a more refined or expansive data sample.
      • Customize the data sample to display data between specific dates and times.

      When analyzing these metrics, don't be concerned about any single standalone metric in the charts and graphs. Rather, you should establish a baseline for your metrics over the course of time, e.g. the range of values that your components usually operate within and are considered normal. After you establish the baseline, be on the lookout for any large deltas in the charts and graphs, as these big changes usually indicate a problem that you need to investigate.

      Grafana​

      If you've enabled monitoring at either the cluster level or project level, Rancher automatically creates a link to Grafana instance. Use this link to view monitoring data.

      Grafana allows you to query, visualize, alert, and ultimately, understand your cluster and workload data. For more information on Grafana and its capabilities, visit the Grafana website.

      Authentication​

      Rancher determines which users can access the new Grafana instance, as well as the objects they can view within it, by validating them against the user's cluster or project roles. In other words, a user's access in Grafana mirrors their access in Rancher.

      When you go to the Grafana instance, you will be logged in with the username admin and the password admin. If you log out and log in again, you will be prompted to change your password. You will only have access to the URL of the Grafana instance if you have access to view the corresponding metrics in Rancher. So for example, if your Rancher permissions are scoped to the project level, you won't be able to see the Grafana instance for cluster-level metrics.

      Accessing the Cluster-level Grafana Instance​

      1. From the Global view, navigate to a cluster that has monitoring enabled.

      2. Go to the System project view. This project is where the cluster-level Grafana instance runs.

      3. Click Apps. In versions before v2.2.0, choose Catalog Apps on the main navigation bar.

      4. Go to the cluster-monitoring application.

      5. In the cluster-monitoring application, there are two /index.html links: one that leads to a Grafana instance and one that leads to a Prometheus instance. When you click the Grafana link, it will redirect you to a new webpage for Grafana, which shows metrics for the cluster.

      6. You will be signed in to the Grafana instance automatically. The default username is admin and the default password is admin. For security, we recommend that you log out of Grafana, log back in with the admin password, and change your password.

      Results: You are logged into Grafana from the Grafana instance. After logging in, you can view the preset Grafana dashboards, which are imported via the Grafana provisioning mechanism, so you cannot modify them directly. For now, if you want to configure your own dashboards, clone the original and modify the new copy.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html b/v2.0-v2.4/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html index a089b85b0fe..b388b245573 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html @@ -5,13 +5,13 @@ CPU and Memory Allocations | Rancher Manager - +
      Version: v2.0-v2.4

      CPU and Memory Allocations

      Available as of v2.3.0

      This section describes the minimum recommended computing resources for the Istio components in a cluster.

      The CPU and memory allocations for each component are configurable.

      Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

      Tip: In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.

      The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each central Istio component.

      In Kubernetes, the resource request indicates that the workload will not deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the Kubernetes documentation.

      WorkloadContainerCPU - RequestMem - RequestCPU - LimitMem - LimitConfigurable
      istio-pilotdiscovery500m2048Mi1000m4096MiY
      istio-telemetrymixer1000m1024Mi4800m4096MiY
      istio-policymixer1000m1024Mi4800m4096MiY
      istio-tracingjaeger100m100Mi500m1024MiY
      prometheusprometheus750m750Mi1000m1024MiY
      grafanagrafana100m100Mi200m512MiY
      Others-500m500Mi--N
      Total-3950m5546Mi>12300m>14848Mi-

      Configuring Resource Allocations​

      You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component.

      To make it easier to schedule the workloads to a node, a cluster administrator can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend.

      You can find more information about Istio configuration in the official Istio documentation.

      To configure the resources allocated to an Istio component,

      1. In Rancher, go to the cluster where you have Istio installed.
      2. Click Tools > Istio. This opens the Istio configuration page.
      3. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations.
      4. Click Save.

      Result: The resource allocations for the Istio components are updated.

      Pilot​

      Pilot provides the following:

      • Authentication configuration
      • Service discovery for the Envoy sidecars
      • Traffic management capabilities for intelligent routing (A/B tests and canary rollouts)
      • Configuration for resiliency (timeouts, retries, circuit breakers, etc)

      For more information on Pilot, refer to the documentation.

      OptionDescriptionRequiredDefault
      Pilot CPU LimitCPU resource limit for the istio-pilot pod.Yes1000
      Pilot CPU ReservationCPU reservation for the istio-pilot pod.Yes500
      Pilot Memory LimitMemory resource limit for the istio-pilot pod.Yes4096
      Pilot Memory ReservationMemory resource requests for the istio-pilot pod.Yes2048
      Trace sampling PercentageTrace sampling percentageYes1
      Pilot SelectorAbility to select the nodes in which istio-pilot pod is deployed to. To use this option, the nodes must have labels.Non/a

      Mixer​

      Mixer enforces access control and usage policies across the service mesh. It also integrates with plugins for monitoring tools such as Prometheus. The Envoy sidecar proxy passes telemetry data and monitoring data to Mixer, and Mixer passes the monitoring data to Prometheus.

      For more information on Mixer, policies and telemetry, refer to the documentation.

      OptionDescriptionRequiredDefault
      Mixer Telemetry CPU LimitCPU resource limit for the istio-telemetry pod.Yes4800
      Mixer Telemetry CPU ReservationCPU reservation for the istio-telemetry pod.Yes1000
      Mixer Telemetry Memory LimitMemory resource limit for the istio-telemetry pod.Yes4096
      Mixer Telemetry Memory ReservationMemory resource requests for the istio-telemetry pod.Yes1024
      Enable Mixer PolicyWhether or not to deploy the istio-policy.YesFalse
      Mixer Policy CPU LimitCPU resource limit for the istio-policy pod.Yes, when policy enabled4800
      Mixer Policy CPU ReservationCPU reservation for the istio-policy pod.Yes, when policy enabled1000
      Mixer Policy Memory LimitMemory resource limit for the istio-policy pod.Yes, when policy enabled4096
      Mixer Policy Memory ReservationMemory resource requests for the istio-policy pod.Yes, when policy enabled1024
      Mixer SelectorAbility to select the nodes in which istio-policy and istio-telemetry pods are deployed to. To use this option, the nodes must have labels.Non/a

      Tracing​

      Distributed tracing enables users to track a request through a service mesh. This makes it easier to troubleshoot problems with latency, parallelism and serialization.

      OptionDescriptionRequiredDefault
      Enable TracingWhether or not to deploy the istio-tracing.YesTrue
      Tracing CPU LimitCPU resource limit for the istio-tracing pod.Yes500
      Tracing CPU ReservationCPU reservation for the istio-tracing pod.Yes100
      Tracing Memory LimitMemory resource limit for the istio-tracing pod.Yes1024
      Tracing Memory ReservationMemory resource requests for the istio-tracing pod.Yes100
      Tracing SelectorAbility to select the nodes in which tracing pod is deployed to. To use this option, the nodes must have labels.Non/a

      Ingress Gateway​

      The Istio gateway allows Istio features such as monitoring and route rules to be applied to traffic entering the cluster. This gateway is a prerequisite for outside traffic to make requests to Istio.

      For more information, refer to the documentation.

      OptionDescriptionRequiredDefault
      Enable Ingress GatewayWhether or not to deploy the istio-ingressgateway.YesFalse
      Service Type of Istio Ingress GatewayHow to expose the gateway. You can choose NodePort or LoadbalancerYesNodePort
      Http2 PortThe NodePort for http2 requestsYes31380
      Https PortThe NodePort for https requestsYes31390
      Load Balancer IPIngress Gateway Load Balancer IPNon/a
      Load Balancer Source RangesIngress Gateway Load Balancer Source RangesNon/a
      Ingress Gateway CPU LimitCPU resource limit for the istio-ingressgateway pod.Yes2000
      Ingress Gateway CPU ReservationCPU reservation for the istio-ingressgateway pod.Yes100
      Ingress Gateway Memory LimitMemory resource limit for the istio-ingressgateway pod.Yes1024
      Ingress Gateway Memory ReservationMemory resource requests for the istio-ingressgateway pod.Yes128
      Ingress Gateway SelectorAbility to select the nodes in which istio-ingressgateway pod is deployed to. To use this option, the nodes must have labels.Non/a

      Prometheus​

      You can query for Istio metrics using Prometheus. Prometheus is an open-source systems monitoring and alerting toolkit.

      OptionDescriptionRequiredDefault
      Prometheus CPU LimitCPU resource limit for the Prometheus pod.Yes1000
      Prometheus CPU ReservationCPU reservation for the Prometheus pod.Yes750
      Prometheus Memory LimitMemory resource limit for the Prometheus pod.Yes1024
      Prometheus Memory ReservationMemory resource requests for the Prometheus pod.Yes750
      Retention for PrometheusHow long your Prometheus instance retains dataYes6
      Prometheus SelectorAbility to select the nodes in which Prometheus pod is deployed to. To use this option, the nodes must have labels.Non/a

      Grafana​

      You can visualize metrics with Grafana. Grafana lets you visualize Istio traffic data scraped by Prometheus.

      OptionDescriptionRequiredDefault
      Enable GrafanaWhether or not to deploy the Grafana.YesTrue
      Grafana CPU LimitCPU resource limit for the Grafana pod.Yes, when Grafana enabled200
      Grafana CPU ReservationCPU reservation for the Grafana pod.Yes, when Grafana enabled100
      Grafana Memory LimitMemory resource limit for the Grafana pod.Yes, when Grafana enabled512
      Grafana Memory ReservationMemory resource requests for the Grafana pod.Yes, when Grafana enabled100
      Grafana SelectorAbility to select the nodes in which Grafana pod is deployed to. To use this option, the nodes must have labels.Non/a
      Enable Persistent Storage for GrafanaEnable Persistent Storage for GrafanaYes, when Grafana enabledFalse
      SourceUse a Storage Class to provision a new persistent volume or Use an existing persistent volume claimYes, when Grafana enabled and enabled PVUse SC
      Storage ClassStorage Class for provisioning PV for GrafanaYes, when Grafana enabled, enabled PV and use storage classUse the default class
      Persistent Volume SizeThe size for the PV you would like to provision for GrafanaYes, when Grafana enabled, enabled PV and use storage class5Gi
      Existing ClaimUse existing PVC for GrafanaYes, when Grafana enabled, enabled PV and use existing PVCn/a
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/istio/disable-istio.html b/v2.0-v2.4/explanations/integrations-in-rancher/istio/disable-istio.html index aafc4a94c8f..5da24a18f0c 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/istio/disable-istio.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/istio/disable-istio.html @@ -5,13 +5,13 @@ Disabling Istio | Rancher Manager - +
      Version: v2.0-v2.4

      Disabling Istio

      This section describes how to disable Istio in a cluster, namespace, or workload.

      Disable Istio in a Cluster

      To disable Istio,

      1. From the Global view, navigate to the cluster that you want to disable Istio for.
      2. Click Tools > Istio.
      3. Click Disable, then click the red button again to confirm the disable action.

      Result: The cluster-istio application in the cluster's system project gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster.

      Disable Istio in a Namespace

      1. In the Rancher UI, go to the project that has the namespace where you want to disable Istio.
      2. On the Workloads tab, you will see a list of namespaces and the workloads deployed in them. Go to the namespace where you want to disable and click the ⋮ > Disable Istio Auto Injection.

      Result: When workloads are deployed in this namespace, they will not have the Istio sidecar.

      Remove the Istio Sidecar from a Workload

      Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.html b/v2.0-v2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.html index a4e0ef200ef..0a48631de80 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/istio/rbac-for-istio.html @@ -5,13 +5,13 @@ Role-based Access Control | Rancher Manager - +
      Version: v2.0-v2.4

      Role-based Access Control

      This section describes the permissions required to access Istio features and how to configure access to the Kiali and Jaeger visualizations.

      Cluster-level Access

      By default, only cluster administrators can:

      • Enable Istio for the cluster
      • Configure resource allocations for Istio
      • View each UI for Prometheus, Grafana, Kiali, and Jaeger

      Project-level Access

      After Istio is enabled in a cluster, project owners and members have permission to:

      • Enable and disable Istio sidecar auto-injection for namespaces
      • Add the Istio sidecar to workloads
      • View the traffic metrics and traffic graph for the cluster
      • View the Kiali and Jaeger visualizations if cluster administrators give access to project members
      • Configure Istio's resources (such as the gateway, destination rules, or virtual services) with kubectl (This does not apply to read-only project members)

      Access to Visualizations

      By default, the Kiali and Jaeger visualizations are restricted to the cluster owner because the information in them could be sensitive.

      Jaeger provides a UI for a distributed tracing system, which is useful for root cause analysis and for determining what causes poor performance.

      Kiali provides a diagram that shows the services within a service mesh and how they are connected.

      Rancher supports giving groups permission to access Kiali and Jaeger, but not individuals.

      To configure who has permission to access the Kiali and Jaeger UI,

      1. Go to the cluster view and click Tools > Istio.
      2. Then go to the Member Access section. If you want to restrict access to certain groups, choose Allow cluster owner and specified members to access Kiali and Jaeger UI. Search for the groups that you want to have access to Kiali and Jaeger. If you want all members to have access to the tools, click Allow all members to access Kiali and Jaeger UI.
      3. Click Save.

      Result: The access levels for Kiali and Jaeger have been updated.

      Summary of Default Permissions for Istio Users

      PermissionCluster AdministratorsProject OwnersProject MembersRead-only Project Members
      Enable and disable Istio for the cluster✓
      Configure Istio resource limits✓
      Control who has access to Kiali and the Jaeger UI✓
      Enable and disable Istio for a namespace✓✓✓
      Enable and disable Istio on workloads✓✓✓
      Configure Istio with kubectl✓✓✓
      View Prometheus UI and Grafana UI✓
      View Kiali UI and Jaeger UI (Configurable)✓
      View Istio project dashboard, including traffic metrics*✓✓✓✓
      • By default, only the cluster owner will see the traffic graph. Project members will see only a subset of traffic metrics. Project members cannot see the traffic graph because it comes from Kiali, and access to Kiali is restricted to cluster owners by default.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/istio/release-notes.html b/v2.0-v2.4/explanations/integrations-in-rancher/istio/release-notes.html index 45c8450e09b..3302b49d614 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/istio/release-notes.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/istio/release-notes.html @@ -5,13 +5,13 @@ Release Notes | Rancher Manager - +
      Version: v2.0-v2.4

      Istio 1.5.8

      Important note on 1.5.x versions​

      When upgrading from any 1.4 version of Istio to any 1.5 version, the Rancher installer will delete several resources in order to complete the upgrade, at which point they will be immediately re-installed. This includes the istio-reader-service-account. If your Istio installation is using this service account be aware that any secrets tied to the service account will be deleted. Most notably this will break specific multi-cluster deployments. Downgrades back to 1.4 are not possible.

      See the official upgrade notes for additional information on the 1.5 release and upgrading from 1.4: https://istio.io/latest/news/releases/1.5.x/announcing-1.5/upgrade-notes/

      Note: Rancher continues to use the Helm installation method, which produces a different architecture from an istioctl installation.

      Known Issues​

      • The Kiali traffic graph is currently not working #24924
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/notifiers.html b/v2.0-v2.4/explanations/integrations-in-rancher/notifiers.html index 0352c912435..4dede9bc10a 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/notifiers.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/notifiers.html @@ -5,13 +5,13 @@ Notifiers | Rancher Manager - +
      Version: v2.0-v2.4

      Notifiers

      Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action.

      Rancher integrates with a variety of popular IT services, including:

      • Slack: Send alert notifications to your Slack channels.
      • Email: Choose email recipients for alert notifications.
      • PagerDuty: Route notifications to staff by phone, SMS, or personal email.
      • WebHooks: Update a webpage with alert notifications.
      • WeChat: (Available as of v2.2.0) Send alert notifications to your Enterprise WeChat contacts.
      • DingTalk: (Available as of v2.4.6) Send alert notifications to DingTalk using a webhook.
      • Microsoft Teams: (Available as of v2.4.6) Send alert notifications to Teams using a webhook.

      Roles-based Access Control for Notifiers

      Notifiers are configured at the cluster level. This model ensures that only cluster owners need to configure notifiers, leaving project owners to simply configure alerts in the scope of their projects. You don't need to dispense privileges like SMTP server access or cloud account access.

      Adding Notifiers

      Set up a notifier so that you can begin configuring and sending alerts.

      1. From the Global View, open the cluster that you want to add a notifier.
      2. From the main menu, select Tools > Notifiers. Then click Add Notifier.
      3. Select the service you want to use as your notifier, and then fill out the form. For help filling out the form, refer to the configuration section below.
      4. Click Test. You should receive a notification confirming that the notifier is configured correctly.
      5. Click Add to complete adding the notifier.

      Result: Your notifier is added to Rancher.

      Configuration

      Slack​

      FieldExplanation
      NameEnter a Name for the notifier.
      URLFrom Slack, create a webhook. For instructions, see the Slack Documentation. Then enter the Slack webhook URL.
      Default ChannelEnter the name of the channel that you want to send alert notifications in the following format: #<channelname>. Both public and private channels are supported.
      Proxy URLProxy for the Slack webhook.
      Send Resolved AlertsAvailable as of v2.3.0 Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, the Slack channel you're configuring for the notifier outputs Slack setting validated.

      Email​

      FieldExplanation
      NameEnter a Name for the notifier.
      Default Recipient AddressEnter the email address that you want to receive the notification.
      Send Resolved AlertsAvailable as of v2.3.0 Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      SMTP Server Configuration:

      FieldExplanation
      SenderEnter an email address available on your mail server that you want to send the notification.
      HostEnter the IP address or hostname for your SMTP server. Example: smtp.email.com
      PortIn the Port field, enter the port used for email. Typically, TLS uses 587 and SSL uses 465.
      Use TLSIf you're using TLS, make sure Use TLS is selected.
      UsernameUsername to authenticate with the SMTP server.
      PasswordPassword to authenticate with the SMTP server.

      Validation: Click Test. If the test is successful, Rancher prints settings validated and you receive a test notification email.

      PagerDuty​

      FieldExplanation
      NameEnter a Name for the notifier.
      Default Integration KeyFrom PagerDuty, create a Prometheus integration. For instructions, see the PagerDuty Documentation. Then enter the integration key.
      Service KeyThe same as the integration key. For instructions on creating a Prometheus integration, see the PagerDuty Documentation. Then enter the integration key.
      Send Resolved AlertsAvailable as of v2.3.0 Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, your PagerDuty endpoint outputs PagerDuty setting validated.

      Webhook​

      FieldExplanation
      NameEnter a Name for the notifier.
      URLUsing the app of your choice, create a webhook URL.
      Proxy URLProxy for the webhook.
      Send Resolved AlertsAvailable as of v2.3.0 Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, the URL you're configuring as a notifier outputs Webhook setting validated.

      WeChat​

      Available as of v2.2.0

      FieldExplanation
      NameEnter a Name for the notifier.
      Corporation IDEnter the "EnterpriseID" of your corporation. You can get it fro the Profile page.
      Application Agent IDFrom Enterprise WeChat, create an application in the Application page, and then enter the "AgentId" of this application. You will also need to enter the application secret.
      Application SecretThe secret that corresponds to the Application Agent ID.
      Recipient TypeParty, tag, or user.
      Default RecipientThe default recipient ID should correspond to the recipient type. It should be the party ID, tag ID or user account that you want to receive the notification. You could get contact information from Contacts page.
      Proxy URLIf you are using a proxy, enter the proxy URL.
      Send Resolved AlertsAvailable as of v2.3.0 Whether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, you should receive an alert message.

      DingTalk​

      Available as of v2.4.6

      FieldExplanation
      NameEnter a Name for the notifier.
      Webhook URLEnter the DingTalk webhook URL. For help setting up the webhook, refer to the DingTalk documentation.
      SecretOptional: Enter a secret for the DingTalk webhook.
      Proxy URLOptional: Enter a proxy for the DingTalk webhook.
      Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, the DingTalk notifier output is DingTalk setting validated.

      Microsoft Teams​

      Available as of v2.4.6

      FieldExplanation
      NameEnter a Name for the notifier.
      Webhook URLEnter the Microsoft Teams webhook URL. For help setting up the webhook, refer to the Teams Documentation.
      Proxy URLOptional: Enter a proxy for the Teams webhook.
      Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage)

      Validation: Click Test. If the test is successful, the Teams notifier output is MicrosoftTeams setting validated.

      Managing Notifiers

      After you set up notifiers, you can manage them. From the Global view, open the cluster that you want to manage your notifiers. Select Tools > Notifiers. You can:

      • Edit their settings that you configured during their initial setup.
      • Clone them, to quickly setup slightly different notifiers.
      • Delete them when they're no longer necessary.

      Example Payload for a Webhook Alert Notifier

      {
        "receiver": "c-2a3bc:kube-components-alert",
        "status": "firing",
        "alerts": [
          {
            "status": "firing",
            "labels": {
              "alert_name": "Scheduler is unavailable",
              "alert_type": "systemService",
              "cluster_name": "mycluster (ID: c-2a3bc)",
              "component_name": "scheduler",
              "group_id": "c-2a3bc:kube-components-alert",
              "logs": "Get http://127.0.0.1:10251/healthz: dial tcp 127.0.0.1:10251: connect: connection refused",
              "rule_id": "c-2a3bc:kube-components-alert_scheduler-system-service",
              "severity": "critical"
            },
            "annotations": {},
            "startsAt": "2020-01-30T19:18:13.321684733Z",
            "endsAt": "0001-01-01T00:00:00Z",
            "generatorURL": ""
          }
        ],
        "groupLabels": {
          "component_name": "scheduler",
          "rule_id": "c-2a3bc:kube-components-alert_scheduler-system-service"
        },
        "commonLabels": {
          "alert_name": "Scheduler is unavailable",
          "alert_type": "systemService",
          "cluster_name": "mycluster (ID: c-2a3bc)"
        }
      }

      What's Next?

      After creating a notifier, set up alerts to receive notifications of Rancher system events.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/explanations/integrations-in-rancher/opa-gatekeeper.html b/v2.0-v2.4/explanations/integrations-in-rancher/opa-gatekeeper.html index f789099ebb3..1bfe6863b24 100644 --- a/v2.0-v2.4/explanations/integrations-in-rancher/opa-gatekeeper.html +++ b/v2.0-v2.4/explanations/integrations-in-rancher/opa-gatekeeper.html @@ -5,13 +5,13 @@ OPA Gatekeeper | Rancher Manager - +
      Version: v2.0-v2.4

      OPA Gatekeeper

      Available as of v2.4.0

      To ensure consistency and compliance, every organization needs the ability to define and enforce policies in its environment in an automated way. OPA (Open Policy Agent) is a policy engine that facilitates policy-based control for cloud native environments. Rancher provides the ability to enable OPA Gatekeeper in Kubernetes clusters, and also installs a couple of built-in policy definitions, which are also called constraint templates.

      OPA provides a high-level declarative language that lets you specify policy as code and ability to extend simple APIs to offload policy decision-making.

      OPA Gatekeeper is a project that provides integration between OPA and Kubernetes. OPA Gatekeeper provides:

      • An extensible, parameterized policy library.
      • Native Kubernetes CRDs for instantiating the policy library, also called “constraints."
      • Native Kubernetes CRDs for extending the policy library, also called "constraint templates."
      • Audit functionality.

      To read more about OPA, please refer to the official documentation.

      How the OPA Gatekeeper Integration Works​

      Kubernetes provides the ability to extend API server functionality via admission controller webhooks, which are invoked whenever a resource is created, updated or deleted. Gatekeeper is installed as a validating webhook and enforces policies defined by Kubernetes custom resource definitions. In addition to the admission control usage, Gatekeeper provides the capability to audit existing resources in Kubernetes clusters and mark current violations of enabled policies.

      OPA Gatekeeper is made available via Rancher's Helm system chart, and it is installed in a namespace named gatekeeper-system.

      Enabling OPA Gatekeeper in a Cluster​

      Prerequisites:

      • Only administrators and cluster owners can enable OPA Gatekeeper.
      • The dashboard needs to be enabled using the dashboard feature flag. For more information, refer to the section on enabling experimental features.
      1. Navigate to the cluster's Dashboard view.
      2. On the left side menu, expand the cluster menu and click on OPA Gatekeeper.
      3. To install Gatekeeper with the default configuration, click on Enable Gatekeeper (v0.1.0) with defaults.
      4. To change any default configuration, click on Customize Gatekeeper yaml configuration.

      Constraint Templates​

      Constraint templates are Kubernetes custom resources that define the schema and Rego logic of the OPA policy to be applied by Gatekeeper. For more information on the Rego policy language, refer to the official documentation.

      When OPA Gatekeeper is enabled, Rancher installs some templates by default.

      To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on Templates.

      Rancher also provides the ability to create your own constraint templates by importing YAML definitions.

      Creating and Configuring Constraints​

      Constraints are Kubernetes custom resources that define the scope of objects to which a specific constraint template applies to. The complete policy is defined by constraint templates and constraints together.

      Prerequisites: OPA Gatekeeper must be enabled in the cluster.

      To list the constraints installed, go to the left side menu under OPA Gatekeeper, and click on Constraints.

      New constraints can be created from a constraint template.

      Rancher provides the ability to create a constraint by using a convenient form that lets you input the various constraint fields.

      The Edit as yaml option is also available to configure the the constraint's yaml definition.

      Exempting Rancher's System Namespaces from Constraints​

      When a constraint is created, ensure that it does not apply to any Rancher or Kubernetes system namespaces. If the system namespaces are not excluded, then it is possible to see many resources under them marked as violations of the constraint.

      To limit the scope of the constraint only to user namespaces, always specify these namespaces under the Match field of the constraint.

      Also, the constraint may interfere with other Rancher functionality and deny system workloads from being deployed. To avoid this, exclude all Rancher-specific namespaces from your constraints.

      Enforcing Constraints in your Cluster​

      When the Enforcement Action is Deny, the constraint is immediately enabled and will deny any requests that violate the policy defined. By default, the enforcement value is Deny.

      When the Enforcement Action is Dryrun, then any resources that violate the policy are only recorded under the constraint's status field.

      To enforce constraints, create a constraint using the form. In the Enforcement Action field, choose Deny.

      Audit and Violations in your Cluster​

      OPA Gatekeeper runs a periodic audit to check if any existing resource violates any enforced constraint. The audit-interval (default 300s) can be configured while installing Gatekeeper.

      On the Gatekeeper page, any violations of the defined constraints are listed.

      Also under Constraints, the number of violations of the constraint can be found.

      The detail view of each constraint lists information about the resource that violated the constraint.

      Disabling Gatekeeper​

      1. Navigate to the cluster's Dashboard view
      2. On the left side menu, expand the cluster menu and click on OPA Gatekeeper.
      3. Click the ⋮ > Disable.

      Result: Upon disabling OPA Gatekeeper, all constraint templates and constraints will also be deleted.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq.html b/v2.0-v2.4/faq.html index 1caf1eaa2f4..41f661a7a1f 100644 --- a/v2.0-v2.4/faq.html +++ b/v2.0-v2.4/faq.html @@ -5,13 +5,13 @@ FAQ | Rancher Manager - +
      Version: v2.0-v2.4

      FAQ

      This FAQ is a work in progress designed to answers the questions our users most frequently ask about Rancher v2.x.

      See Technical FAQ, for frequently asked technical questions.


      Does Rancher v2.x support Docker Swarm and Mesos as environment types?

      When creating an environment in Rancher v2.x, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm.


      Is it possible to manage Azure Kubernetes Services with Rancher v2.x?

      Yes.


      Does Rancher support Windows?

      As of Rancher 2.3.0, we support Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on configuring custom clusters for Windows.


      Does Rancher support Istio?

      As of Rancher 2.3.0, we support Istio.

      Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along with any CNCF compliant Kubernetes cluster. You can read more about it here


      Will Rancher v2.x support Hashicorp's Vault for storing secrets?

      Secrets management is on our roadmap but we haven't assigned it to a specific release yet.


      Does Rancher v2.x support RKT containers as well?

      At this time, we only support Docker.


      Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and imported Kubernetes?

      Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave (Weave is available as of v2.2.0). Always refer to the Rancher Support Matrix for details about what is officially supported.


      Are you planning on supporting Traefik for existing setups?

      We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches.


      Can I import OpenShift Kubernetes clusters into v2.x?

      Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.


      Are you going to integrate Longhorn?

      Yes. Longhorn was on a bit of a hiatus while we were working on v2.0. We plan to re-engage on the project.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/container-network-interface-providers.html b/v2.0-v2.4/faq/container-network-interface-providers.html index 79c07b74ce1..b62918bc166 100644 --- a/v2.0-v2.4/faq/container-network-interface-providers.html +++ b/v2.0-v2.4/faq/container-network-interface-providers.html @@ -5,13 +5,13 @@ Container Network Interface (CNI) Providers | Rancher Manager - +
      Version: v2.0-v2.4

      Container Network Interface (CNI) Providers

      What is CNI?​

      CNI (Container Network Interface), a Cloud Native Computing Foundation project, consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted.

      Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking.

      CNI Logo

      For more information visit CNI GitHub project.

      What Network Models are Used in CNI?​

      CNI network providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan (VXLAN) or an unencapsulated network model such as Border Gateway Protocol (BGP).

      What is an Encapsulated Network?​

      This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP.

      In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected.

      This network model is used when an extended L2 bridge is preferred. This network model is sensitive to L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation.

      CNI network providers using this network model include Flannel, Canal, and Weave.

      Encapsulated Network

      What is an Unencapsulated Network?​

      This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as BGP.

      In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods.

      This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensitive to latency.

      CNI network providers using this network model include Calico and Romana.

      Unencapsulated Network

      What CNI Providers are Provided by Rancher?​

      Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave (Weave is available as of v2.2.0). You can choose your CNI network provider when you create new Kubernetes clusters from Rancher.

      Canal​

      Canal Logo

      Canal is a CNI network provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options.

      In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation.

      Kubernetes workers should open UDP port 8472 (VXLAN) and TCP port 9099 (healthcheck). For details, refer to the port requirements for user clusters.

      For more information, see the Canal GitHub Page.

      Flannel​

      Flannel Logo

      Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being VXLAN.

      Encapsulated traffic is unencrypted by default. Therefore, flannel provides an experimental backend for encryption, IPSec, which makes use of strongSwan to establish encrypted IPSec tunnels between Kubernetes workers.

      Kubernetes workers should open UDP port 8472 (VXLAN) and TCP port 9099 (healthcheck). See the port requirements for user clusters for more details.

      Flannel Diagram

      For more information, see the Flannel GitHub Page.

      Calico​

      Calico Logo

      Calico enables networking and network policy in Kubernetes clusters across the cloud. Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-prem using BGP.

      Calico also provides a stateless IP-in-IP encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies.

      Kubernetes workers should open TCP port 179 (BGP). See the port requirements for user clusters for more details.

      Calico Diagram

      For more information, see the following pages:

      Weave​

      Weave Logo

      Available as of v2.2.0

      Weave enables networking and network policy in Kubernetes clusters across the cloud. Additionally, it support encrypting traffic between the peers.

      Kubernetes workers should open TCP port 6783 (control port), UDP port 6783 and UDP port 6784 (data ports). See the port requirements for user clusters for more details.

      For more information, see the following pages:

      CNI Features by Provider​

      The following table summarizes the different features available for each CNI network provider provided by Rancher.

      ProviderNetwork ModelRoute DistributionNetwork PoliciesMeshExternal DatastoreEncryptionIngress/Egress Policies
      CanalEncapsulated (VXLAN)NoYesNoK8S APINoYes
      FlannelEncapsulated (VXLAN)NoNoNoK8S APINoNo
      CalicoEncapsulated (VXLAN,IPIP) OR UnencapsulatedYesYesYesEtcd and K8S APINoYes
      WeaveEncapsulatedYesYesYesNoYesYes

      • Network Model: Encapsulated or unencapsulated. For more information, see What Network Models are Used in CNI?

      • Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI network providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have.

      • Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with certain networking plugins.

      • Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters.

      • External Datastore: CNI network providers with this feature need an external datastore for its data.

      • Encryption: This feature allows cyphered and secure network control and data planes.

      • Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications.

      CNI Community Popularity​

      The following table summarizes different GitHub metrics to give you an idea of each project's popularity and activity. This data was collected in January 2020.

      ProviderProjectStarsForksContributors
      Canalhttps://github.com/projectcalico/canal6148919
      flannelhttps://github.com/coreos/flannel49771.4k140
      Calicohttps://github.com/projectcalico/calico1534429135
      Weavehttps://github.com/weaveworks/weave/573755973

      ### Which CNI Provider Should I Use?

      It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs.

      As of Rancher v2.0.7, Canal is the default CNI network provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking.

      How can I configure a CNI network provider?​

      Please see Cluster Options on how to configure a network provider for your cluster. For more advanced configuration options, please see how to configure your cluster using a Config File and the options for Network Plug-ins.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/install-and-configure-kubectl.html b/v2.0-v2.4/faq/install-and-configure-kubectl.html index 47c959b32da..a1ecb3b9db6 100644 --- a/v2.0-v2.4/faq/install-and-configure-kubectl.html +++ b/v2.0-v2.4/faq/install-and-configure-kubectl.html @@ -5,13 +5,13 @@ Installing and Configuring kubectl | Rancher Manager - +
      Version: v2.0-v2.4

      Installing and Configuring kubectl

      kubectl is a CLI utility for running commands against Kubernetes clusters. It's required for many maintenance and administrative tasks in Rancher 2.x.

      Installation​

      See kubectl Installation for installation on your operating system.

      Configuration​

      When you create a Kubernetes cluster with RKE, RKE creates a kube_config_rancher-cluster.yml in the local directory that contains credentials to connect to your new cluster with tools like kubectl or helm.

      You can copy this file to $HOME/.kube/config or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_rancher-cluster.yml.

      export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml

      Test your connectivity with kubectl and see if you can get the list of nodes back.

      kubectl get nodes
       NAME                          STATUS    ROLES                      AGE       VERSION
      165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.10.1
      165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.10.1
      165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.10.1
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/networking.html b/v2.0-v2.4/faq/networking.html index 9ea0160174d..b29403992ab 100644 --- a/v2.0-v2.4/faq/networking.html +++ b/v2.0-v2.4/faq/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/rancher-is-no-longer-needed.html b/v2.0-v2.4/faq/rancher-is-no-longer-needed.html index 8e5e632a1bf..e571404c465 100644 --- a/v2.0-v2.4/faq/rancher-is-no-longer-needed.html +++ b/v2.0-v2.4/faq/rancher-is-no-longer-needed.html @@ -5,13 +5,13 @@ Rancher is No Longer Needed | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher is No Longer Needed

      This page is intended to answer questions about what happens if you don't want Rancher anymore, if you don't want a cluster to be managed by Rancher anymore, or if the Rancher server is deleted.

      If the Rancher server is deleted, what happens to the workloads in my downstream clusters?​

      If Rancher is ever deleted or unrecoverable, all workloads in the downstream Kubernetes clusters managed by Rancher will continue to function as normal.

      If the Rancher server is deleted, how do I access my downstream clusters?​

      The capability to access a downstream cluster without Rancher depends on the type of cluster and the way that the cluster was created. To summarize:

      • Imported clusters: The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was imported into Rancher.
      • Hosted Kubernetes clusters: If you created the cluster in a cloud-hosted Kubernetes provider such as EKS, GKE, or AKS, you can continue to manage the cluster using your provider's cloud credentials.
      • RKE clusters: To access an RKE cluster, the cluster must have the authorized cluster endpoint enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. (The authorized cluster endpoint is enabled by default for RKE clusters.) With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's authentication proxy. For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with kubectl and the kubeconfig file. These clusters will use a snapshot of the authentication as it was configured when Rancher was removed.

      What if I don't want Rancher anymore?​

      If you installed Rancher on a Kubernetes cluster, remove Rancher by using the System Tools with the remove subcommand.

      If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in.

      Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on accessing downstream clusters when Rancher is removed.

      What if I don't want my imported cluster managed by Rancher?​

      If an imported cluster is deleted from the Rancher UI, the cluster is detached from Rancher, leaving it intact and accessible by the same methods that were used to access it before it was imported into Rancher.

      To detach the cluster,

      1. From the Global view in Rancher, go to the Clusters tab.
      2. Go to the imported cluster that should be detached from Rancher and click ⋮ > Delete.
      3. Click Delete.

      Result: The imported cluster is detached from Rancher and functions normally outside of Rancher.

      What if I don't want my RKE cluster or hosted Kubernetes cluster managed by Rancher?​

      At this time, there is no functionality to detach these clusters from Rancher. In this context, "detach" is defined as the ability to remove Rancher components from the cluster and manage access to the cluster independently of Rancher.

      The capability to manage these clusters without Rancher is being tracked in this issue.

      For information about how to access clusters if the Rancher server is deleted, refer to this section.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/security.html b/v2.0-v2.4/faq/security.html index dedd9dc38f9..a49c50f2fa9 100644 --- a/v2.0-v2.4/faq/security.html +++ b/v2.0-v2.4/faq/security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
      Version: v2.0-v2.4

      Security

      Is there a Hardening Guide?

      The Hardening Guide is now located in the main Security section.


      What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?

      We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main Security section.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/technical-items.html b/v2.0-v2.4/faq/technical-items.html index 0c6325777f7..f2b50ffb02c 100644 --- a/v2.0-v2.4/faq/technical-items.html +++ b/v2.0-v2.4/faq/technical-items.html @@ -5,13 +5,13 @@ Technical | Rancher Manager - +
      Version: v2.0-v2.4

      Technical

      How can I reset the administrator password?​

      Docker Install:

      $ docker exec -ti <container_id> reset-password
      New password for default administrator (user-xxxxx):
      <new_password>

      Kubernetes install (Helm):

      $ KUBECONFIG=./kube_config_rancher-cluster.yml
      $ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- reset-password
      New password for default administrator (user-xxxxx):
      <new_password>

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Kubernetes install (RKE add-on):

      $ KUBECONFIG=./kube_config_rancher-cluster.yml
      $ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name=="cattle-server") | .metadata.name') -- reset-password
      New password for default administrator (user-xxxxx):
      <new_password>

      I deleted/deactivated the last admin, how can I fix it?​

      Docker Install:

      $ docker exec -ti <container_id> ensure-default-admin
      New default administrator (user-xxxxx)
      New password for default administrator (user-xxxxx):
      <new_password>

      Kubernetes install (Helm):

      $ KUBECONFIG=./kube_config_rancher-cluster.yml
      $ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin
      New password for default administrator (user-xxxxx):
      <new_password>

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Kubernetes install (RKE add-on):

      $ KUBECONFIG=./kube_config_rancher-cluster.yml
      $ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name=="cattle-server") | .metadata.name') -- ensure-default-admin
      New password for default admin user (user-xxxxx):
      <new_password>

      How can I enable debug logging?​

      See Troubleshooting: Logging

      My ClusterIP does not respond to ping​

      ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using curl to access the IP and port to see if it responds.

      Where can I manage Node Templates?​

      Node Templates can be accessed by opening your account menu (top right) and selecting Node Templates.

      Why is my Layer-4 Load Balancer in Pending state?​

      The Layer-4 Load Balancer is created as type: LoadBalancer. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in Pending state forever. More information can be found on Cloud Providers or Create External Load Balancer

      Where is the state of Rancher stored?​

      • Docker Install: in the embedded etcd of the rancher/rancher container, located at /var/lib/rancher.
      • Kubernetes install: in the etcd of the RKE cluster created to run Rancher.

      How are the supported Docker versions determined?​

      We follow the validated Docker versions for upstream Kubernetes releases. The validated versions can be found under External Dependencies in the Kubernetes release CHANGELOG.md.

      How can I access nodes created by Rancher?​

      SSH keys to access the nodes created by Rancher can be downloaded via the Nodes view. Choose the node which you want to access and click on the vertical ⋮ button at the end of the row, and choose Download Keys as shown in the picture below.

      Download Keys

      Unzip the downloaded zip file, and use the file id_rsa to connect to you host. Be sure to use the correct username (rancher or docker for RancherOS, ubuntu for Ubuntu, ec2-user for Amazon Linux)

      $ ssh -i id_rsa user@ip_of_node

      How can I automate task X in Rancher?​

      The UI consists of static files, and works based on responses of the API. That means every action/task that you can execute in the UI, can be automated via the API. There are 2 ways to do this:

      • Visit https://your_rancher_ip/v3 and browse the API options.
      • Capture the API calls when using the UI (Most commonly used for this is Chrome Developer Tools but you can use anything you like)

      The IP address of a node changed, how can I recover?​

      A node is required to have a static IP configured (or a reserved IP via DHCP). If the IP of a node has changed, you will have to remove it from the cluster and readd it. After it is removed, Rancher will update the cluster to the correct state. If the cluster is no longer in Provisioning state, the node is removed from the cluster.

      When the IP address of the node changed, Rancher lost connection to the node, so it will be unable to clean the node properly. See Cleaning cluster nodes to clean the node.

      When the node is removed from the cluster, and the node is cleaned, you can readd the node to the cluster.

      How can I add additional arguments/binds/environment variables to Kubernetes components in a Rancher Launched Kubernetes cluster?​

      You can add additional arguments/binds/environment variables via the Config File option in Cluster Options. For more information, see the Extra Args, Extra Binds, and Extra Environment Variables in the RKE documentation or browse the Example Cluster.ymls.

      How do I check if my certificate chain is valid?​

      Use the openssl verify command to validate your certificate chain:

      Note: Configure SSL_CERT_DIR and SSL_CERT_FILE to a dummy location to make sure the OS installed certificates are not used when verifying manually.

      SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem
      rancher.yourdomain.com.pem: OK

      If you receive the error unable to get local issuer certificate, the chain is incomplete. This usually means that there is an intermediate CA certificate that issued your server certificate. If you already have this certificate, you can use it in the verification of the certificate like shown below:

      SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem
      rancher.yourdomain.com.pem: OK

      If you have successfully verified your certificate chain, you should include needed intermediate CA certificates in the server certificate to complete the certificate chain for any connection made to Rancher (for example, by the Rancher agent). The order of the certificates in the server certificate file should be first the server certificate itself (contents of rancher.yourdomain.com.pem), followed by intermediate CA certificate(s) (contents of intermediate.pem).

      -----BEGIN CERTIFICATE-----
      %YOUR_CERTIFICATE%
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      %YOUR_INTERMEDIATE_CERTIFICATE%
      -----END CERTIFICATE-----

      If you still get errors during verification, you can retrieve the subject and the issuer of the server certificate using the following command:

      openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem
      subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com
      issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA

      How do I check Common Name and Subject Alternative Names in my server certificate?​

      Although technically an entry in Subject Alternative Names is required, having the hostname in both Common Name and as entry in Subject Alternative Names gives you maximum compatibility with older browser/applications.

      Check Common Name:

      openssl x509 -noout -subject -in cert.pem
      subject= /CN=rancher.my.org

      Check Subject Alternative Names:

      openssl x509 -noout -in cert.pem -text | grep DNS
                      DNS:rancher.my.org

      Why does it take 5+ minutes for a pod to be rescheduled when a node has failed?​

      This is due to a combination of the following default Kubernetes settings:

      • kubelet
        • node-status-update-frequency: Specifies how often kubelet posts node status to master (default 10s)
      • kube-controller-manager
        • node-monitor-period: The period for syncing NodeStatus in NodeController (default 5s)
        • node-monitor-grace-period: Amount of time which we allow running Node to be unresponsive before marking it unhealthy (default 40s)
        • pod-eviction-timeout: The grace period for deleting pods on failed nodes (default 5m0s)

      See Kubernetes: kubelet and Kubernetes: kube-controller-manager for more information on these settings.

      In Kubernetes v1.13, the TaintBasedEvictions feature is enabled by default. See Kubernetes: Taint based Evictions for more information.

      • kube-apiserver (Kubernetes v1.13 and up)
        • default-not-ready-toleration-seconds: Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration.
        • default-unreachable-toleration-seconds: Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration.

      Can I use keyboard shortcuts in the UI?​

      Yes, most parts of the UI can be reached using keyboard shortcuts. For an overview of the available shortcuts, press ? anywhere in the UI.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/telemetry.html b/v2.0-v2.4/faq/telemetry.html index 88ff099f261..775e3c144cd 100644 --- a/v2.0-v2.4/faq/telemetry.html +++ b/v2.0-v2.4/faq/telemetry.html @@ -5,13 +5,13 @@ Telemetry | Rancher Manager - +
      Version: v2.0-v2.4

      Telemetry

      What is Telemetry?​

      Telemetry collects aggregate information about the size of Rancher installations, versions of components used, and which features are used. This information is used by Rancher Labs to help make the product better and is not shared with third-parties.

      What information is collected?​

      No specific identifying information like usernames, passwords, or the names or addresses of user resources will ever be collected.

      The primary things collected include:

      • Aggregate counts (smallest, average, largest, total) of nodes per-cluster and their size (e.g. CPU cores & RAM).
      • Aggregate counts of logical resources like Clusters, Projects, Namespaces, and Pods.
      • Counts of what driver was used to deploy clusters and nodes (e.g. GKE vs EC2 vs Imported vs Custom).
      • Versions of Kubernetes components, Operating Systems and Docker that are deployed on nodes.
      • Whether some optional components are enabled or not (e.g. which auth providers are used).
      • The image name & version of Rancher that is running.
      • A unique randomly-generated identifier for this installation.

      Can I see the information that is being sent?​

      If Telemetry is enabled, you can go to https://<your rancher server>/v1-telemetry in your installation to see the current data.

      If Telemetry is not enabled, the process that collects the data is not running, so there is nothing being collected to look at.

      How do I turn it on or off?​

      After initial setup, an administrator can go to the Settings page in the Global section of the UI and click Edit to change the telemetry-opt setting to either in or out.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/faq/upgrades-to-2x.html b/v2.0-v2.4/faq/upgrades-to-2x.html index 98ad68061d8..d47479ae420 100644 --- a/v2.0-v2.4/faq/upgrades-to-2x.html +++ b/v2.0-v2.4/faq/upgrades-to-2x.html @@ -5,13 +5,13 @@ Questions about Upgrading to Rancher v2.x | Rancher Manager - +
      Version: v2.0-v2.4

      Questions about Upgrading to Rancher v2.x

      This page contains frequently asked questions about the changes between Rancher v1.x and v2.x, and how to upgrade from Rancher v1.x to v2.x.

      Kubernetes

      What does it mean when you say Rancher v2.x is built on Kubernetes?

      Rancher v2.x is a complete container management platform built 100% on Kubernetes leveraging its Custom Resource and Controller framework. All features are written as a CustomResourceDefinition (CRD) which extends the existing Kubernetes API and can leverage native features such as RBAC.


      Do you plan to implement upstream Kubernetes, or continue to work on your own fork?

      We're still going to provide our distribution when you select the default option of having us create your Kubernetes cluster, but it will be very close to upstream.


      Does this release mean that we need to re-train our support staff in Kubernetes?

      Yes. Rancher will offer the native Kubernetes functionality via kubectl but will also offer our own UI dashboard to allow you to deploy Kubernetes workload without having to understand the full complexity of Kubernetes. However, to fully leverage Kubernetes, we do recommend understanding Kubernetes. We do plan on improving our UX with subsequent releases to make Kubernetes easier to use.


      Is a Rancher compose going to make a Kubernetes pod? Do we have to learn both now? We usually use the filesystem layer of files, not the UI.

      No. Unfortunately, the differences were enough such that we cannot support Rancher compose anymore in 2.x. We will be providing both a tool and guides to help with this migration.


      If we use Kubernetes native YAML files for creating resources, should we expect that to work as expected, or do we need to use Rancher/Docker compose files to deploy infrastructure?

      Absolutely.

      Cattle

      How does Rancher v2.x affect Cattle?

      Cattle will not supported in v2.x as Rancher has been re-architected to be based on Kubernetes. You can, however, expect majority of Cattle features you use will exist and function similarly on Kubernetes. We will develop migration tools in Rancher v2.1 to help you transform your existing Rancher Compose files into Kubernetes YAML files.


      Can I migrate existing Cattle workloads into Kubernetes?

      Yes. In the upcoming Rancher v2.1 release we will provide a tool to help translate existing Cattle workloads in Compose format to Kubernetes YAML format. You will then be able to deploy those workloads on the v2.x platform.

      Feature Changes

      Can we still add our own infrastructure services, which had a separate view/filter in 1.6.x?

      Yes. You can manage Kubernetes storage, networking, and its vast ecosystem of add-ons.


      Are there changes to default roles available now or going forward? Will the Kubernetes alignment impact plans for roles/RBAC?

      The default roles will be expanded to accommodate the new Rancher 2.x features, and will also take advantage of the Kubernetes RBAC (Role-Based Access Control) capabilities to give you more flexibility.


      Will there be any functions like network policies to separate a front-end container from a back-end container through some kind of firewall in v2.x?

      Yes. You can do so by leveraging Kubernetes' network policies.


      What about the CLI? Will that work the same way with the same features?

      Yes. Definitely.

      Environments & Clusters

      Can I still create templates for environments and clusters?

      Starting with 2.0, the concept of an environment has now been changed to a Kubernetes cluster as going forward, only the Kubernetes orchestration engine is supported.

      Kubernetes RKE Templates is on our roadmap for 2.x. Please refer to our Release Notes and documentation for all the features that we currently support.


      Can you still add an existing host to an environment? (i.e. not provisioned directly from Rancher)

      Yes. We still provide you with the same way of executing our Rancher agents directly on hosts.

      Upgrading/Migrating

      How would the migration from v1.x to v2.x work?

      Due to the technical difficulty in transforming a Docker container into a pod running Kubernetes, upgrading will require users to "replay" those workloads from v1.x into new v2.x environments. We plan to ship with a tool in v2.1 to translate existing Rancher Compose files into Kubernetes YAML files. You will then be able to deploy those workloads on the v2.x platform.


      Is it possible to upgrade from Rancher v1.x to v2.x without any disruption to Cattle and Kubernetes clusters?

      At this time, we are still exploring this scenario and taking feedback. We anticipate that you will need to launch a new Rancher instance and then relaunch on v2.x. Once you've moved to v2.x, upgrades will be in place, as they are in v1.6.

      Support

      Are you planning some long-term support releases for Rancher v1.6?

      That is definitely the focus of the v1.6 stream. We're continuing to improve that release, fix bugs, and maintain it. New releases of the v1.6 stream are announced in the Rancher forums. The Rancher wiki contains the v1.6 release notes.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started.html b/v2.0-v2.4/getting-started.html index 0c56f2122ed..cfc736e0b93 100644 --- a/v2.0-v2.4/getting-started.html +++ b/v2.0-v2.4/getting-started.html @@ -5,13 +5,13 @@ Getting Started | Rancher Manager - +
      Version: v2.0-v2.4

      Getting Started

      To get up and running with Rancher quickly, we have included a Getting Started section.

      The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

      Please see the introduction, quick start guides, and the installation and upgrade sections for more.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.html index 64d9d7d3259..b524f93bfab 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/install-rancher.html @@ -5,7 +5,7 @@ 4. Install Rancher | Rancher Manager - + @@ -14,7 +14,7 @@ Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade cert-manager documentation.

      1. From a system connected to the internet, add the cert-manager repo to Helm.

        helm repo add jetstack https://charts.jetstack.io
        helm repo update

      2. Fetch the latest cert-manager chart available from the Helm chart repository.

        helm fetch jetstack/cert-manager --version v0.14.2

      3. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

        helm template ./cert-manager-v0.14.2.tgz --output-dir . \
            --name cert-manager --namespace cert-manager \
            --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
            --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
            --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

      4. Download the required CRD file for cert-manager

        curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.14/deploy/manifests/00-crds.yaml

      5. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

      Placeholder | Description
      ------------|-------------
      `<VERSION>` | The version number of the output tarball.
      `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
      `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
      `<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.

       ```plain
      helm template ./rancher-<VERSION>.tgz --output-dir . \
       --name rancher \
       --namespace cattle-system \
       --set hostname=<RANCHER.YOURDOMAIN.COM> \
       --set certmanager.version=<CERTMANAGER_VERSION> \
       --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
       --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
       --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

      </details>

      <details id="secret">
        <summary>Option B: Certificates From Files using Kubernetes Secrets</summary>

      Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.

      Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

      | Placeholder                      | Description                                     |
      | -------------------------------- | ----------------------------------------------- |
      | `<VERSION>`                      | The version number of the output tarball.       |
      | `<RANCHER.YOURDOMAIN.COM>`       | The DNS name you pointed at your load balancer. |
      | `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.         |

      ```plain
         helm template ./rancher-<VERSION>.tgz --output-dir . \
          --name rancher \
          --namespace cattle-system \
          --set hostname=<RANCHER.YOURDOMAIN.COM> \
          --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
          --set ingress.tls.source=secret \
          --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
          --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

      If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

         helm template ./rancher-<VERSION>.tgz --output-dir . \
          --name rancher \
          --namespace cattle-system \
          --set hostname=<RANCHER.YOURDOMAIN.COM> \
          --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
          --set ingress.tls.source=secret \
          --set privateCA=true \
          --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
          --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

      Then refer to Adding TLS Secrets to publish the certificate files so Rancher and the ingress controller can use them.

      D. Install Rancher​

      Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.

      Use kubectl to create namespaces and apply the rendered manifests.

      If you choose to use self-signed certificates in B. Choose your SSL Configuration, install cert-manager.

      Self-Signed Certificate Installs - Install Cert-manager

      If you are using self-signed certificates, install cert-manager:

      1. Create the namespace for cert-manager.
      kubectl create namespace cert-manager
      1. Create the cert-manager CustomResourceDefinitions (CRDs).
      kubectl apply -f cert-manager/cert-manager-crd.yaml

      Important: If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false flag to your kubectl apply command above else you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

      1. Launch cert-manager.
      kubectl apply -R -f ./cert-manager

      Install Rancher:

      kubectl create namespace cattle-system
      kubectl -n cattle-system apply -R -f ./rancher

      Step Result: If you are installing Rancher v2.3.0+, the installation is complete.

      E. For Rancher versions before v2.3.0, Configure System Charts​

      If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in Github, an air gapped installation will not be able to access these charts. Therefore, you must configure the Rancher system charts.

      Additional Resources​

      These resources could be helpful when installing Rancher:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/launch-kubernetes.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/launch-kubernetes.html index 87ff2ea6f70..d15dafae464 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/launch-kubernetes.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/launch-kubernetes.html @@ -5,14 +5,14 @@ 3. Install Kubernetes with RKE (Kubernetes Installs Only) | Rancher Manager - +
      Version: v2.0-v2.4

      3. Install Kubernetes with RKE (Kubernetes Installs Only)

      This section is about how to prepare to launch a Kubernetes cluster which is used to deploy Rancher server for your air gapped environment.

      Since a Kubernetes Installation requires a Kubernetes cluster, we will create a Kubernetes cluster using Rancher Kubernetes Engine (RKE). Before being able to start your Kubernetes cluster, you'll need to install RKE and create a RKE config file.

      A. Create an RKE Config File​

      From a system that can access ports 22/tcp and 6443/tcp on your host nodes, use the sample below to create a new file named rancher-cluster.yml. This file is a Rancher Kubernetes Engine configuration file (RKE config file), which is a configuration for the cluster you're deploying Rancher to.

      Replace values in the code sample below with help of the RKE Options table. Use the IP address or DNS names of the 3 nodes you created.

      Tip: For more details on the options available, see the RKE Config Options.

      RKE Options
      OptionRequiredDescription
      address✓The DNS or IP address for the node within the air gap network.
      user✓A user that can run docker commands.
      role✓List of Kubernetes roles assigned to the node.
      internal_addressoptional1The DNS or IP address used for internal cluster traffic.
      ssh_key_pathPath to SSH private key used to authenticate to the node (defaults to ~/.ssh/id_rsa).
      1 Some services like AWS EC2 require setting the `internal_address` if you want to use self-referencing security groups or firewalls.
      nodes:
        - address: 10.10.3.187 # node air gap network IP
          internal_address: 172.31.7.22 # node intra-cluster IP
          user: rancher
          role: ['controlplane', 'etcd', 'worker']
          ssh_key_path: /home/user/.ssh/id_rsa
        - address: 10.10.3.254 # node air gap network IP
          internal_address: 172.31.13.132 # node intra-cluster IP
          user: rancher
          role: ['controlplane', 'etcd', 'worker']
          ssh_key_path: /home/user/.ssh/id_rsa
        - address: 10.10.3.89 # node air gap network IP
          internal_address: 172.31.3.216 # node intra-cluster IP
          user: rancher
          role: ['controlplane', 'etcd', 'worker']
          ssh_key_path: /home/user/.ssh/id_rsa

      private_registries:
        - url: <REGISTRY.YOURDOMAIN.COM:PORT> # private registry url
          user: rancher
          password: '*********'
          is_default: true

      B. Run RKE​

      After configuring rancher-cluster.yml, bring up your Kubernetes cluster:

      rke up --config ./rancher-cluster.yml

      C. Save Your Files​

      Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

      Save a copy of the following files in a secure location:

      • rancher-cluster.yml: The RKE cluster configuration file.
      • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
      • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains credentials for full access to the cluster.

        The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher.

      Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

      Next: Install Rancher​

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/populate-private-registry.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/populate-private-registry.html index 30e8ced05e1..be99d351991 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/populate-private-registry.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/populate-private-registry.html @@ -5,7 +5,7 @@ 2. Collect and Publish Images to your Private Registry | Rancher Manager - + @@ -20,7 +20,7 @@ D. Populate the private registry

      Collecting and Populating Linux Images into the Private Registry

      Prerequisites​

      You must populate the private registry with the Windows images before populating the private registry with Linux images. If you have already populated the registry with Linux images, you will need to follow these instructions again as they will publish manifests that support Windows and Linux images.

      These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.

      The workstation must have Docker 18.02+ in order to support manifests, which are required when provisioning Windows clusters.

      A. Find the required assets for your Rancher version​

      1. Browse to our releases page and find the Rancher v2.x.x release that you want to install. Don't download releases marked rc or Pre-release, as they are not stable for production environments.

      2. From the release's Assets section, download the following files, which are required to install Rancher in an air gap environment:

      Release FileDescription
      rancher-images.txtThis file contains a list of images needed to install Rancher, provision clusters and user Rancher tools.
      rancher-windows-images.txtThis file contains a list of images needed to provision Windows clusters.
      rancher-save-images.shThis script pulls all the images in the rancher-images.txt from Docker Hub and saves all of the images as rancher-images.tar.gz.
      rancher-load-images.shThis script loads images from the rancher-images.tar.gz file and pushes them to your private registry.

      B. Collect all the required images​

      For Kubernetes Installs using Rancher Generated Self-Signed Certificate: In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the cert-manager image to rancher-images.txt as well. You skip this step if you are using you using your own certificates.

      1. Fetch the latest cert-manager Helm chart and parse the template for image details:

        Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

        helm repo add jetstack https://charts.jetstack.io
        helm repo update
        helm fetch jetstack/cert-manager --version v0.14.2
        helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt

      2. Sort and unique the images list to remove any overlap between the sources:

        sort -u rancher-images.txt -o rancher-images.txt

      C. Save the images to your workstation​

      1. Make rancher-save-images.sh an executable:

        chmod +x rancher-save-images.sh

      2. Run rancher-save-images.sh with the rancher-images.txt image list to create a tarball of all the required images:

        ./rancher-save-images.sh --image-list ./rancher-images.txt

        Result: Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named rancher-images.tar.gz. Check that the output is in the directory.

      D. Populate the private registry​

      Move the images in the rancher-images.tar.gz to your private registry using the rancher-load-images.sh script to load the images. The rancher-images.txt / rancher-windows-images.txt image list is expected to be on the workstation in the same directory that you are running the rancher-load-images.sh script.

      1. Log into your private registry if required:

        docker login <REGISTRY.YOURDOMAIN.COM:PORT>

      2. Make rancher-load-images.sh an executable:

        chmod +x rancher-load-images.sh

      3. Use rancher-load-images.sh to extract, tag and push the images from rancher-images.tar.gz to your private registry:

        ./rancher-load-images.sh --image-list ./rancher-images.txt \
          --windows-image-list ./rancher-windows-images.txt \
          --registry <REGISTRY.YOURDOMAIN.COM:PORT>

      Next: Kubernetes Installs - Launch a Kubernetes Cluster with RKE​

      Next: Docker Installs - Install Rancher​

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.html index c9dfbe16f1e..0bfa36f0228 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/air-gap-helm2/prepare-nodes.html @@ -5,14 +5,14 @@ 1. Prepare your Node(s) | Rancher Manager - +
      Version: v2.0-v2.4

      1. Prepare your Node(s)

      This section is about how to prepare your node(s) to install Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are tabs for either a high availability (recommended) or a Docker installation.

      Prerequisites

      OS, Docker, Hardware, and Networking​

      Make sure that your node(s) fulfill the general installation requirements.

      Private Registry​

      Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.

      If you need help with creating a private registry, please refer to the Docker documentation.

      CLI Tools​

      The following CLI tools are required for the Kubernetes Install. Make sure these tools are installed on your workstation and available in your $PATH.

      • kubectl - Kubernetes command-line tool.
      • rke - Rancher Kubernetes Engine, cli for building Kubernetes clusters.
      • helm - Package management for Kubernetes. Refer to the Helm version requirements to choose a version of Helm to install Rancher.

      Set up Infrastructure

      Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

      • DNS for Rancher should resolve to a layer 4 load balancer
      • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
      • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
      • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
      Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at ingress controllers

      Rancher HA

      A. Provision three air gapped Linux hosts according to our requirements​

      These hosts will be disconnected from the internet, but require being able to connect with your private registry.

      View hardware and software requirements for each of your cluster nodes in Requirements.

      B. Set up your Load Balancer​

      When setting up the Kubernetes cluster that will run the Rancher server components, an Ingress controller pod will be deployed on each of your nodes. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server.

      You will need to configure a load balancer as a basic Layer 4 TCP forwarder to direct traffic to these ingress controller pods. The exact configuration will vary depending on your environment.

      Important: Only use this load balancer (i.e, the local cluster Ingress) to load balance the Rancher server. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps.

      Load Balancer Configuration Samples:

      • For an example showing how to set up an NGINX load balancer, refer to this page.
      • For an example showing how to set up an Amazon NLB load balancer, refer to this page.

      Next: Collect and Publish Images to your Private Registry​

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate-recognizedca.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate-recognizedca.html index cbcb3d779bb..25473e4097f 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate-recognizedca.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate-recognizedca.html @@ -5,13 +5,13 @@ Template for an RKE Cluster with a Certificate Signed by Recognized CA and a Layer 4 Load Balancer | Rancher Manager - +
      Version: v2.0-v2.4

      Template for an RKE Cluster with a Certificate Signed by Recognized CA and a Layer 4 Load Balancer

      RKE uses a cluster.yml file to install and configure your Kubernetes cluster.

      This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.

      The following template can be used for the cluster.yml if you have a setup with:

      For more options, refer to RKE Documentation: Config Options.

      nodes:
        - address: <IP> # hostname or IP to access nodes
          user: <USER> # root user (usually 'root')
          role: [controlplane,etcd,worker] # K8s roles for node
          ssh_key_path: <PEM_FILE> # path to PEM file
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>

      services:
        etcd:
          snapshot: true
          creation: 6h
          retention: 24h

      addons: |-
        ---
        kind: Namespace
        apiVersion: v1
        metadata:
          name: cattle-system
        ---
        kind: ServiceAccount
        apiVersion: v1
        metadata:
          name: cattle-admin
          namespace: cattle-system
        ---
        kind: ClusterRoleBinding
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: cattle-crb
          namespace: cattle-system
        subjects:
        - kind: ServiceAccount
          name: cattle-admin
          namespace: cattle-system
        roleRef:
          kind: ClusterRole
          name: cluster-admin
          apiGroup: rbac.authorization.k8s.io
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-ingress
          namespace: cattle-system
        type: Opaque
        data:
          tls.crt: <BASE64_CRT>  # ssl cert for ingress. If self-signed, must be signed by same CA as cattle server
          tls.key: <BASE64_KEY>  # ssl key for ingress. If self-signed, must be signed by same CA as cattle server
        ---
        apiVersion: v1
        kind: Service
        metadata:
          namespace: cattle-system
          name: cattle-service
          labels:
            app: cattle
        spec:
          ports:
          - port: 80
            targetPort: 80
            protocol: TCP
            name: http
          - port: 443
            targetPort: 443
            protocol: TCP
            name: https
          selector:
            app: cattle
        ---
        apiVersion: extensions/v1beta1
        kind: Ingress
        metadata:
          namespace: cattle-system
          name: cattle-ingress-http
          annotations:
            nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
            nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
        spec:
          rules:
          - host: <FQDN>  # FQDN to access cattle server
            http:
              paths:
              - backend:
                  serviceName: cattle-service
                  servicePort: 80
          tls:
          - secretName: cattle-keys-ingress
            hosts:
            - <FQDN>      # FQDN to access cattle server
        ---
        kind: Deployment
        apiVersion: extensions/v1beta1
        metadata:
          namespace: cattle-system
          name: cattle
        spec:
          replicas: 1
          template:
            metadata:
              labels:
                app: cattle
            spec:
              serviceAccountName: cattle-admin
              containers:
              # Rancher install via RKE addons is only supported up to v2.0.8
              - image: rancher/rancher:v2.0.8
                args:
                - --no-cacerts
                imagePullPolicy: Always
                name: cattle-server
        #       env:
        #       - name: HTTP_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: HTTPS_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: NO_PROXY
        #         value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
                livenessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 60
                  periodSeconds: 60
                readinessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 20
                  periodSeconds: 10
                ports:
                - containerPort: 80
                  protocol: TCP
                - containerPort: 443
                  protocol: TCP
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate.html index 9db690e07c4..8c89edafc0b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-certificate.html @@ -5,13 +5,13 @@ Template for an RKE Cluster with a Self-signed Certificate and Layer 4 Load Balancer | Rancher Manager - +
      Version: v2.0-v2.4

      Template for an RKE Cluster with a Self-signed Certificate and Layer 4 Load Balancer

      RKE uses a cluster.yml file to install and configure your Kubernetes cluster.

      This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.

      The following template can be used for the cluster.yml if you have a setup with:

      For more options, refer to RKE Documentation: Config Options.

      nodes:
        - address: <IP> # hostname or IP to access nodes
          user: <USER> # root user (usually 'root')
          role: [controlplane,etcd,worker] # K8s roles for node
          ssh_key_path: <PEM_FILE> # path to PEM file
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>

      services:
        etcd:
          snapshot: true
          creation: 6h
          retention: 24h

      addons: |-
        ---
        kind: Namespace
        apiVersion: v1
        metadata:
          name: cattle-system
        ---
        kind: ServiceAccount
        apiVersion: v1
        metadata:
          name: cattle-admin
          namespace: cattle-system
        ---
        kind: ClusterRoleBinding
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: cattle-crb
          namespace: cattle-system
        subjects:
        - kind: ServiceAccount
          name: cattle-admin
          namespace: cattle-system
        roleRef:
          kind: ClusterRole
          name: cluster-admin
          apiGroup: rbac.authorization.k8s.io
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-ingress
          namespace: cattle-system
        type: Opaque
        data:
          tls.crt: <BASE64_CRT>  # ssl cert for ingress. If selfsigned, must be signed by same CA as cattle server
          tls.key: <BASE64_KEY>  # ssl key for ingress. If selfsigned, must be signed by same CA as cattle server
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-server
          namespace: cattle-system
        type: Opaque
        data:
          cacerts.pem: <BASE64_CA>  # CA cert used to sign cattle server cert and key
        ---
        apiVersion: v1
        kind: Service
        metadata:
          namespace: cattle-system
          name: cattle-service
          labels:
            app: cattle
        spec:
          ports:
          - port: 80
            targetPort: 80
            protocol: TCP
            name: http
          - port: 443
            targetPort: 443
            protocol: TCP
            name: https
          selector:
            app: cattle
        ---
        apiVersion: extensions/v1beta1
        kind: Ingress
        metadata:
          namespace: cattle-system
          name: cattle-ingress-http
          annotations:
            nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
            nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
        spec:
          rules:
          - host: <FQDN>  # FQDN to access cattle server
            http:
              paths:
              - backend:
                  serviceName: cattle-service
                  servicePort: 80
          tls:
          - secretName: cattle-keys-ingress
            hosts:
            - <FQDN>      # FQDN to access cattle server
        ---
        kind: Deployment
        apiVersion: extensions/v1beta1
        metadata:
          namespace: cattle-system
          name: cattle
        spec:
          replicas: 1
          template:
            metadata:
              labels:
                app: cattle
            spec:
              serviceAccountName: cattle-admin
              containers:
              # Rancher install via RKE addons is only supported up to v2.0.8
              - image: rancher/rancher:v2.0.8
                imagePullPolicy: Always
                name: cattle-server
        #       env:
        #       - name: HTTP_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: HTTPS_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: NO_PROXY
        #         value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
                livenessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 60
                  periodSeconds: 60
                readinessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 20
                  periodSeconds: 10
                ports:
                - containerPort: 80
                  protocol: TCP
                - containerPort: 443
                  protocol: TCP
                volumeMounts:
                - mountPath: /etc/rancher/ssl
                  name: cattle-keys-volume
                  readOnly: true
              volumes:
              - name: cattle-keys-volume
                secret:
                  defaultMode: 420
                  secretName: cattle-keys-server
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-certificate.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-certificate.html index 6de340fd35e..6627eaa9a9b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-certificate.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-certificate.html @@ -5,13 +5,13 @@ Template for an RKE Cluster with a Self-signed Certificate and SSL Termination on Layer 7 Load Balancer | Rancher Manager - +
      Version: v2.0-v2.4

      Template for an RKE Cluster with a Self-signed Certificate and SSL Termination on Layer 7 Load Balancer

      RKE uses a cluster.yml file to install and configure your Kubernetes cluster.

      This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.

      The following template can be used for the cluster.yml if you have a setup with:

      For more options, refer to RKE Documentation: Config Options.

      nodes:
        - address: <IP> # hostname or IP to access nodes
          user: <USER> # root user (usually 'root')
          role: [controlplane,etcd,worker] # K8s roles for node
          ssh_key_path: <PEM_FILE> # path to PEM file
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>

      services:
        etcd:
          snapshot: true
          creation: 6h
          retention: 24h

      addons: |-
        ---
        kind: Namespace
        apiVersion: v1
        metadata:
          name: cattle-system
        ---
        kind: ServiceAccount
        apiVersion: v1
        metadata:
          name: cattle-admin
          namespace: cattle-system
        ---
        kind: ClusterRoleBinding
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: cattle-crb
          namespace: cattle-system
        subjects:
        - kind: ServiceAccount
          name: cattle-admin
          namespace: cattle-system
        roleRef:
          kind: ClusterRole
          name: cluster-admin
          apiGroup: rbac.authorization.k8s.io
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-server
          namespace: cattle-system
        type: Opaque
        data:
          cacerts.pem: <BASE64_CA>  # CA cert used to sign cattle server cert and key
        ---
        apiVersion: v1
        kind: Service
        metadata:
          namespace: cattle-system
          name: cattle-service
          labels:
            app: cattle
        spec:
          ports:
          - port: 80
            targetPort: 80
            protocol: TCP
            name: http
          selector:
            app: cattle
        ---
        apiVersion: extensions/v1beta1
        kind: Ingress
        metadata:
          namespace: cattle-system
          name: cattle-ingress-http
          annotations:
            nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
            nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/ssl-redirect: "false"        # Disable redirect to ssl
        spec:
          rules:
          - host: <FQDN>
            http:
              paths:
              - backend:
                  serviceName: cattle-service
                  servicePort: 80
        ---
        kind: Deployment
        apiVersion: extensions/v1beta1
        metadata:
          namespace: cattle-system
          name: cattle
        spec:
          replicas: 1
          template:
            metadata:
              labels:
                app: cattle
            spec:
              serviceAccountName: cattle-admin
              containers:
              # Rancher install via RKE addons is only supported up to v2.0.8
              - image: rancher/rancher:v2.0.8
                imagePullPolicy: Always
                name: cattle-server
        #       env:
        #       - name: HTTP_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: HTTPS_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: NO_PROXY
        #         value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
                livenessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 60
                  periodSeconds: 60
                readinessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 20
                  periodSeconds: 10
                ports:
                - containerPort: 80
                  protocol: TCP
                volumeMounts:
                - mountPath: /etc/rancher/ssl
                  name: cattle-keys-volume
                  readOnly: true
              volumes:
              - name: cattle-keys-volume
                secret:
                  defaultMode: 420
                  secretName: cattle-keys-server
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-recognizedca.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-recognizedca.html index 3a928005ad3..47ebbbab894 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-recognizedca.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/cluster-yml-templates/node-externalssl-recognizedca.html @@ -5,13 +5,13 @@ Template for an RKE Cluster with a Recognized CA Certificate and SSL Termination on Layer 7 Load Balancer | Rancher Manager - +
      Version: v2.0-v2.4

      Template for an RKE Cluster with a Recognized CA Certificate and SSL Termination on Layer 7 Load Balancer

      RKE uses a cluster.yml file to install and configure your Kubernetes cluster.

      This template is intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.

      The following template can be used for the cluster.yml if you have a setup with:

      For more options, refer to RKE Documentation: Config Options.

      nodes:
        - address: <IP> # hostname or IP to access nodes
          user: <USER> # root user (usually 'root')
          role: [controlplane,etcd,worker] # K8s roles for node
          ssh_key_path: <PEM_FILE> # path to PEM file
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>
        - address: <IP>
          user: <USER>
          role: [controlplane,etcd,worker]
          ssh_key_path: <PEM_FILE>

      services:
        etcd:
          snapshot: true
          creation: 6h
          retention: 24h

      addons: |-
        ---
        kind: Namespace
        apiVersion: v1
        metadata:
          name: cattle-system
        ---
        kind: ServiceAccount
        apiVersion: v1
        metadata:
          name: cattle-admin
          namespace: cattle-system
        ---
        kind: ClusterRoleBinding
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: cattle-crb
          namespace: cattle-system
        subjects:
        - kind: ServiceAccount
          name: cattle-admin
          namespace: cattle-system
        roleRef:
          kind: ClusterRole
          name: cluster-admin
          apiGroup: rbac.authorization.k8s.io
        ---
        apiVersion: v1
        kind: Service
        metadata:
          namespace: cattle-system
          name: cattle-service
          labels:
            app: cattle
        spec:
          ports:
          - port: 80
            targetPort: 80
            protocol: TCP
            name: http
          selector:
            app: cattle
        ---
        apiVersion: extensions/v1beta1
        kind: Ingress
        metadata:
          namespace: cattle-system
          name: cattle-ingress-http
          annotations:
            nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
            nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/ssl-redirect: "false"        # Disable redirect to ssl
        spec:
          rules:
          - host: <FQDN>
            http:
              paths:
              - backend:
                  serviceName: cattle-service
                  servicePort: 80
        ---
        kind: Deployment
        apiVersion: extensions/v1beta1
        metadata:
          namespace: cattle-system
          name: cattle
        spec:
          replicas: 1
          template:
            metadata:
              labels:
                app: cattle
            spec:
              serviceAccountName: cattle-admin
              containers:
              # Rancher install via RKE addons is only supported up to v2.0.8
              - image: rancher/rancher:v2.0.8
                args:
                - --no-cacerts
                imagePullPolicy: Always
                name: cattle-server
        #       env:
        #       - name: HTTP_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: HTTPS_PROXY
        #         value: "http://your_proxy_address:port"
        #       - name: NO_PROXY
        #         value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,your_network_ranges_that_dont_need_proxy_to_access"
                livenessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 60
                  periodSeconds: 60
                readinessProbe:
                  httpGet:
                    path: /ping
                    port: 80
                  initialDelaySeconds: 20
                  periodSeconds: 10
                ports:
                - containerPort: 80
                  protocol: TCP
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html index cee2487b821..ab2646992a9 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html @@ -5,7 +5,7 @@ Docker Install with TLS Termination at Layer-7 NGINX Load Balancer | Rancher Manager - + @@ -13,7 +13,7 @@
      Version: v2.0-v2.4

      Docker Install with TLS Termination at Layer-7 NGINX Load Balancer

      For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction.

      A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.

      This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.

      Want to skip the external load balancer? See Docker Installation instead.

      Requirements for OS, Docker, Hardware, and Networking​

      Make sure that your node fulfills the general installation requirements.

      Installation Outline​

      1. Provision Linux Host​

      Provision a single Linux host according to our Requirements to launch your Rancher Server.

      2. Choose an SSL Option and Install Rancher​

      For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

      Do you want to...

      • Complete an Air Gap Installation?
      • Record all transactions with the Rancher API?

      See Advanced Options below before continuing.

      Choose from the following options:

      Option A-Bring Your Own Certificate: Self-Signed

      If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate.

      Prerequisites: Create a self-signed certificate.

      • The certificate files must be in PEM format.

      To Install Rancher Using a Self-Signed Cert:

      1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.

        docker run -d --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
          rancher/rancher:latest
      Option B-Bring Your Own Certificate: Signed by Recognized CA
      If your cluster is public facing, it's best to use a certificate signed by a recognized CA.

      Prerequisites:

      • The certificate files must be in PEM format.

      To Install Rancher Using a Cert Signed by a Recognized CA:

      If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the --no-cacerts parameter to the container.

      1. Enter the following command.

        ```
        docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        rancher/rancher:latest --no-cacerts
        ```

      3. Configure Load Balancer​

      When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header X-Forwarded-Proto: https header, this redirect is disabled.

      The load balancer or proxy has to be configured to support the following:

      • WebSocket connections

      • SPDY / HTTP/2 protocols

      • Passing / setting the following headers:

        HeaderValueDescription
        HostHostname used to reach Rancher.To identify the server requested by the client.
        X-Forwarded-ProtohttpsTo identify the protocol that a client used to connect to the load balancer or proxy.

        Note: If this header is present, rancher/rancher does not redirect HTTP to HTTPS.
        X-Forwarded-PortPort used to reach Rancher.To identify the protocol that client used to connect to the load balancer or proxy.
        X-Forwarded-ForIP of the client connection.To identify the originating IP address of a client.

      Example NGINX configuration​

      This NGINX configuration is tested on NGINX 1.14.

      Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

      • Replace rancher-server with the IP address or hostname of the node running the Rancher container.
      • Replace both occurrences of FQDN to the DNS name for Rancher.
      • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
      worker_processes 4;
      worker_rlimit_nofile 40000;

      events {
          worker_connections 8192;
      }

      http {
          upstream rancher {
              server rancher-server:80;
          }

          map $http_upgrade $connection_upgrade {
              default Upgrade;
              ''      close;
          }

          server {
              listen 443 ssl http2;
              server_name FQDN;
              ssl_certificate /certs/fullchain.pem;
              ssl_certificate_key /certs/privkey.pem;

              location / {
                  proxy_set_header Host $host;
                  proxy_set_header X-Forwarded-Proto $scheme;
                  proxy_set_header X-Forwarded-Port $server_port;
                  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                  proxy_pass http://rancher;
                  proxy_http_version 1.1;
                  proxy_set_header Upgrade $http_upgrade;
                  proxy_set_header Connection $connection_upgrade;
                  # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                  proxy_read_timeout 900s;
                  proxy_buffering off;
              }
          }

          server {
              listen 80;
              server_name FQDN;
              return 301 https://$server_name$request_uri;
          }
      }

      What's Next?​


      FAQ and Troubleshooting​

      For help troubleshooting certificates, see this section.

      Advanced Options​

      API Auditing​

      If you want to record all transactions with the Rancher API, enable the API Auditing feature by adding the flags below into your install command.

      -e AUDIT_LEVEL=1 \
      -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
      -e AUDIT_LOG_MAXAGE=20 \
      -e AUDIT_LOG_MAXBACKUP=20 \
      -e AUDIT_LOG_MAXSIZE=100 \

      Air Gap​

      If you are visiting this page to complete an Air Gap Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

      Example:

       <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

      Persistent Data​

      Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

      You can bind mount a host volume to this location to preserve data on the host it is running on:

      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /opt/rancher:/var/lib/rancher \
        rancher/rancher:latest

      This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).

      Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - TCP and UDP Load Balancer.

      upstream rancher {
          server rancher-server:80;
      }

      map $http_upgrade $connection_upgrade {
          default Upgrade;
          ''      close;
      }

      server {
          listen 443 ssl http2;
          server_name rancher.yourdomain.com;
          ssl_certificate /etc/your_certificate_directory/fullchain.pem;
          ssl_certificate_key /etc/your_certificate_directory/privkey.pem;

          location / {
              proxy_set_header Host $host;
              proxy_set_header X-Forwarded-Proto $scheme;
              proxy_set_header X-Forwarded-Port $server_port;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_pass http://rancher;
              proxy_http_version 1.1;
              proxy_set_header Upgrade $http_upgrade;
              proxy_set_header Connection $connection_upgrade;
              # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
              proxy_read_timeout 900s;
              proxy_buffering off;
          }
      }

      server {
          listen 80;
          server_name rancher.yourdomain.com;
          return 301 https://$server_name$request_uri;
      }

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html index f389e9cf561..4c99c02e4a5 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html @@ -5,13 +5,13 @@ Enabling the API Audit Log to Record System Events | Rancher Manager - +
      Version: v2.0-v2.4

      Enabling the API Audit Log to Record System Events

      You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.

      You can enable API Auditing during Rancher installation or upgrade.

      Enabling API Audit Log​

      The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.

      API Audit Log Options​

      The usage below defines rules about what the audit log should record and what data it should include:

      ParameterDescription
      AUDIT_LEVEL0 - Disable audit log (default setting).
      1 - Log event metadata.
      2 - Log event metadata and request body.
      3 - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same auditID value.

      See Audit Level Logging for a table that displays what each setting logs.
      AUDIT_LOG_PATHLog path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log. You can mount the log directory to host.

      Usage Example: AUDIT_LOG_PATH=/my/custom/path/
      AUDIT_LOG_MAXAGEDefined the maximum number of days to retain old audit log files. Default is 10 days.
      AUDIT_LOG_MAXBACKUPDefines the maximum number of audit log files to retain. Default is 10.
      AUDIT_LOG_MAXSIZEDefines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M.

      Audit Log Levels​

      The following table displays what parts of API transactions are logged for each AUDIT_LEVEL setting.

      AUDIT_LEVEL SettingRequest MetadataRequest BodyResponse MetadataResponse Body
      0
      1✓
      2✓✓
      3✓✓✓✓

      Viewing API Audit Logs​

      Docker Install​

      Share the AUDIT_LOG_PATH directory (Default: /var/log/auditlog) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc.

      Kubernetes Install​

      Enabling the API Audit Log with the Helm chart install will create a rancher-audit-log sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log.

      The rancher-audit-log container is part of the rancher pod in the cattle-system namespace.

      CLI​

      kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log

      Rancher Web GUI​

      1. From the context menu, select Cluster: local > System.
      2. From the main navigation bar, choose Resources > Workloads. (In versions before v2.3.0, choose Workloads on the main navigation bar.) Find the cattle-system namespace. Open the rancher workload by clicking its link.
      3. Pick one of the rancher pods and select ⋮ > View Logs.
      4. From the Logs drop-down, select rancher-audit-log.

      Shipping the Audit Log​

      You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See Rancher Tools - Logging for details.

      Audit Log Samples​

      After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction.

      Metadata Level​

      If you set your AUDIT_LEVEL to 1, Rancher logs the metadata header for every API request, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc.

      {
        "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183",
        "requestURI": "/v3/schemas",
        "sourceIPs": ["::1"],
        "user": {
          "name": "user-f4tt2",
          "group": ["system:authenticated"]
        },
        "verb": "GET",
        "stage": "RequestReceived",
        "stageTimestamp": "2018-07-20 10:22:43 +0800"
      }

      Metadata and Request Body Level​

      If you set your AUDIT_LEVEL to 2, Rancher logs the metadata header and body for every API request.

      The code sample below depicts an API request, with both its metadata header and body.

      {
        "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb",
        "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
        "sourceIPs": ["::1"],
        "user": {
          "name": "user-f4tt2",
          "group": ["system:authenticated"]
        },
        "verb": "PUT",
        "stage": "RequestReceived",
        "stageTimestamp": "2018-07-20 10:28:08 +0800",
        "requestBody": {
          "hostIPC": false,
          "hostNetwork": false,
          "hostPID": false,
          "paused": false,
          "annotations": {},
          "baseType": "workload",
          "containers": [
            {
              "allowPrivilegeEscalation": false,
              "image": "nginx",
              "imagePullPolicy": "Always",
              "initContainer": false,
              "name": "nginx",
              "ports": [
                {
                  "containerPort": 80,
                  "dnsName": "nginx-nodeport",
                  "kind": "NodePort",
                  "name": "80tcp01",
                  "protocol": "TCP",
                  "sourcePort": 0,
                  "type": "/v3/project/schemas/containerPort"
                }
              ],
              "privileged": false,
              "readOnly": false,
              "resources": {
                "type": "/v3/project/schemas/resourceRequirements",
                "requests": {},
                "limits": {}
              },
              "restartCount": 0,
              "runAsNonRoot": false,
              "stdin": true,
              "stdinOnce": false,
              "terminationMessagePath": "/dev/termination-log",
              "terminationMessagePolicy": "File",
              "tty": true,
              "type": "/v3/project/schemas/container",
              "environmentFrom": [],
              "capAdd": [],
              "capDrop": [],
              "livenessProbe": null,
              "volumeMounts": []
            }
          ],
          "created": "2018-07-18T07:34:16Z",
          "createdTS": 1531899256000,
          "creatorId": null,
          "deploymentConfig": {
            "maxSurge": 1,
            "maxUnavailable": 0,
            "minReadySeconds": 0,
            "progressDeadlineSeconds": 600,
            "revisionHistoryLimit": 10,
            "strategy": "RollingUpdate"
          },
          "deploymentStatus": {
            "availableReplicas": 1,
            "conditions": [
              {
                "lastTransitionTime": "2018-07-18T07:34:38Z",
                "lastTransitionTimeTS": 1531899278000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "Deployment has minimum availability.",
                "reason": "MinimumReplicasAvailable",
                "status": "True",
                "type": "Available"
              },
              {
                "lastTransitionTime": "2018-07-18T07:34:16Z",
                "lastTransitionTimeTS": 1531899256000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
                "reason": "NewReplicaSetAvailable",
                "status": "True",
                "type": "Progressing"
              }
            ],
            "observedGeneration": 2,
            "readyReplicas": 1,
            "replicas": 1,
            "type": "/v3/project/schemas/deploymentStatus",
            "unavailableReplicas": 0,
            "updatedReplicas": 1
          },
          "dnsPolicy": "ClusterFirst",
          "id": "deployment:default:nginx",
          "labels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "name": "nginx",
          "namespaceId": "default",
          "projectId": "c-bcz5t:p-fdr4s",
          "publicEndpoints": [
            {
              "addresses": ["10.64.3.58"],
              "allNodes": true,
              "ingressId": null,
              "nodeId": null,
              "podId": null,
              "port": 30917,
              "protocol": "TCP",
              "serviceId": "default:nginx-nodeport",
              "type": "publicEndpoint"
            }
          ],
          "restartPolicy": "Always",
          "scale": 1,
          "schedulerName": "default-scheduler",
          "selector": {
            "matchLabels": {
              "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
            },
            "type": "/v3/project/schemas/labelSelector"
          },
          "state": "active",
          "terminationGracePeriodSeconds": 30,
          "transitioning": "no",
          "transitioningMessage": "",
          "type": "deployment",
          "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
          "workloadAnnotations": {
            "deployment.kubernetes.io/revision": "1",
            "field.cattle.io/creatorId": "user-f4tt2"
          },
          "workloadLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "scheduling": {
            "node": {}
          },
          "description": "my description",
          "volumes": []
        }
      }

      Metadata, Request Body, and Response Body Level​

      If you set your AUDIT_LEVEL to 3, Rancher logs:

      • The metadata header and body for every API request.
      • The metadata header and body for every API response.

      Request​

      The code sample below depicts an API request, with both its metadata header and body.

      {
        "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
        "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
        "sourceIPs": ["::1"],
        "user": {
          "name": "user-f4tt2",
          "group": ["system:authenticated"]
        },
        "verb": "PUT",
        "stage": "RequestReceived",
        "stageTimestamp": "2018-07-20 10:33:06 +0800",
        "requestBody": {
          "hostIPC": false,
          "hostNetwork": false,
          "hostPID": false,
          "paused": false,
          "annotations": {},
          "baseType": "workload",
          "containers": [
            {
              "allowPrivilegeEscalation": false,
              "image": "nginx",
              "imagePullPolicy": "Always",
              "initContainer": false,
              "name": "nginx",
              "ports": [
                {
                  "containerPort": 80,
                  "dnsName": "nginx-nodeport",
                  "kind": "NodePort",
                  "name": "80tcp01",
                  "protocol": "TCP",
                  "sourcePort": 0,
                  "type": "/v3/project/schemas/containerPort"
                }
              ],
              "privileged": false,
              "readOnly": false,
              "resources": {
                "type": "/v3/project/schemas/resourceRequirements",
                "requests": {},
                "limits": {}
              },
              "restartCount": 0,
              "runAsNonRoot": false,
              "stdin": true,
              "stdinOnce": false,
              "terminationMessagePath": "/dev/termination-log",
              "terminationMessagePolicy": "File",
              "tty": true,
              "type": "/v3/project/schemas/container",
              "environmentFrom": [],
              "capAdd": [],
              "capDrop": [],
              "livenessProbe": null,
              "volumeMounts": []
            }
          ],
          "created": "2018-07-18T07:34:16Z",
          "createdTS": 1531899256000,
          "creatorId": null,
          "deploymentConfig": {
            "maxSurge": 1,
            "maxUnavailable": 0,
            "minReadySeconds": 0,
            "progressDeadlineSeconds": 600,
            "revisionHistoryLimit": 10,
            "strategy": "RollingUpdate"
          },
          "deploymentStatus": {
            "availableReplicas": 1,
            "conditions": [
              {
                "lastTransitionTime": "2018-07-18T07:34:38Z",
                "lastTransitionTimeTS": 1531899278000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "Deployment has minimum availability.",
                "reason": "MinimumReplicasAvailable",
                "status": "True",
                "type": "Available"
              },
              {
                "lastTransitionTime": "2018-07-18T07:34:16Z",
                "lastTransitionTimeTS": 1531899256000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
                "reason": "NewReplicaSetAvailable",
                "status": "True",
                "type": "Progressing"
              }
            ],
            "observedGeneration": 2,
            "readyReplicas": 1,
            "replicas": 1,
            "type": "/v3/project/schemas/deploymentStatus",
            "unavailableReplicas": 0,
            "updatedReplicas": 1
          },
          "dnsPolicy": "ClusterFirst",
          "id": "deployment:default:nginx",
          "labels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "name": "nginx",
          "namespaceId": "default",
          "projectId": "c-bcz5t:p-fdr4s",
          "publicEndpoints": [
            {
              "addresses": ["10.64.3.58"],
              "allNodes": true,
              "ingressId": null,
              "nodeId": null,
              "podId": null,
              "port": 30917,
              "protocol": "TCP",
              "serviceId": "default:nginx-nodeport",
              "type": "publicEndpoint"
            }
          ],
          "restartPolicy": "Always",
          "scale": 1,
          "schedulerName": "default-scheduler",
          "selector": {
            "matchLabels": {
              "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
            },
            "type": "/v3/project/schemas/labelSelector"
          },
          "state": "active",
          "terminationGracePeriodSeconds": 30,
          "transitioning": "no",
          "transitioningMessage": "",
          "type": "deployment",
          "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
          "workloadAnnotations": {
            "deployment.kubernetes.io/revision": "1",
            "field.cattle.io/creatorId": "user-f4tt2"
          },
          "workloadLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "scheduling": {
            "node": {}
          },
          "description": "my decript",
          "volumes": []
        }
      }

      Response​

      The code sample below depicts an API response, with both its metadata header and body.

      {
        "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
        "responseStatus": "200",
        "stage": "ResponseComplete",
        "stageTimestamp": "2018-07-20 10:33:06 +0800",
        "responseBody": {
          "actionLinks": {
            "pause": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=pause",
            "resume": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=resume",
            "rollback": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=rollback"
          },
          "annotations": {},
          "baseType": "workload",
          "containers": [
            {
              "allowPrivilegeEscalation": false,
              "image": "nginx",
              "imagePullPolicy": "Always",
              "initContainer": false,
              "name": "nginx",
              "ports": [
                {
                  "containerPort": 80,
                  "dnsName": "nginx-nodeport",
                  "kind": "NodePort",
                  "name": "80tcp01",
                  "protocol": "TCP",
                  "sourcePort": 0,
                  "type": "/v3/project/schemas/containerPort"
                }
              ],
              "privileged": false,
              "readOnly": false,
              "resources": {
                "type": "/v3/project/schemas/resourceRequirements"
              },
              "restartCount": 0,
              "runAsNonRoot": false,
              "stdin": true,
              "stdinOnce": false,
              "terminationMessagePath": "/dev/termination-log",
              "terminationMessagePolicy": "File",
              "tty": true,
              "type": "/v3/project/schemas/container"
            }
          ],
          "created": "2018-07-18T07:34:16Z",
          "createdTS": 1531899256000,
          "creatorId": null,
          "deploymentConfig": {
            "maxSurge": 1,
            "maxUnavailable": 0,
            "minReadySeconds": 0,
            "progressDeadlineSeconds": 600,
            "revisionHistoryLimit": 10,
            "strategy": "RollingUpdate"
          },
          "deploymentStatus": {
            "availableReplicas": 1,
            "conditions": [
              {
                "lastTransitionTime": "2018-07-18T07:34:38Z",
                "lastTransitionTimeTS": 1531899278000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "Deployment has minimum availability.",
                "reason": "MinimumReplicasAvailable",
                "status": "True",
                "type": "Available"
              },
              {
                "lastTransitionTime": "2018-07-18T07:34:16Z",
                "lastTransitionTimeTS": 1531899256000,
                "lastUpdateTime": "2018-07-18T07:34:38Z",
                "lastUpdateTimeTS": 1531899278000,
                "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
                "reason": "NewReplicaSetAvailable",
                "status": "True",
                "type": "Progressing"
              }
            ],
            "observedGeneration": 2,
            "readyReplicas": 1,
            "replicas": 1,
            "type": "/v3/project/schemas/deploymentStatus",
            "unavailableReplicas": 0,
            "updatedReplicas": 1
          },
          "dnsPolicy": "ClusterFirst",
          "hostIPC": false,
          "hostNetwork": false,
          "hostPID": false,
          "id": "deployment:default:nginx",
          "labels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "links": {
            "remove": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
            "revisions": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/revisions",
            "self": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
            "update": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
            "yaml": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/yaml"
          },
          "name": "nginx",
          "namespaceId": "default",
          "paused": false,
          "projectId": "c-bcz5t:p-fdr4s",
          "publicEndpoints": [
            {
              "addresses": ["10.64.3.58"],
              "allNodes": true,
              "ingressId": null,
              "nodeId": null,
              "podId": null,
              "port": 30917,
              "protocol": "TCP",
              "serviceId": "default:nginx-nodeport"
            }
          ],
          "restartPolicy": "Always",
          "scale": 1,
          "schedulerName": "default-scheduler",
          "selector": {
            "matchLabels": {
              "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
            },
            "type": "/v3/project/schemas/labelSelector"
          },
          "state": "active",
          "terminationGracePeriodSeconds": 30,
          "transitioning": "no",
          "transitioningMessage": "",
          "type": "deployment",
          "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
          "workloadAnnotations": {
            "deployment.kubernetes.io/revision": "1",
            "field.cattle.io/creatorId": "user-f4tt2"
          },
          "workloadLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          }
        }
      }
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nginx.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nginx.html index 8313544e6d1..2c2a20f4a05 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nginx.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nginx.html @@ -5,14 +5,14 @@ NGINX | Rancher Manager - +
      Version: v2.0-v2.4

      NGINX

      NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes.

      Note: In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX.

      One caveat: do not use one of your Rancher nodes as the load balancer.

      Install NGINX​

      Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are 1.14 and 1.15. For help installing NGINX, refer to their install documentation.

      The stream module is required, which is present when using the official NGINX packages. Please refer to your OS documentation on how to install and enable the NGINX stream module on your operating system.

      Create NGINX Configuration​

      After installing NGINX, you need to update the NGINX configuration file, nginx.conf, with the IP addresses for your nodes.

      1. Copy and paste the code sample below into your favorite text editor. Save it as nginx.conf.

      2. From nginx.conf, replace both occurrences (port 80 and port 443) of <IP_NODE_1>, <IP_NODE_2>, and <IP_NODE_3> with the IPs of your nodes.

        Note: See NGINX Documentation: TCP and UDP Load Balancing for all configuration options.

        Example NGINX config
        worker_processes 4;
        worker_rlimit_nofile 40000;

        events {
            worker_connections 8192;
        }

        stream {
            upstream rancher_servers_http {
                least_conn;
                server <IP_NODE_1>:80 max_fails=3 fail_timeout=5s;
                server <IP_NODE_2>:80 max_fails=3 fail_timeout=5s;
                server <IP_NODE_3>:80 max_fails=3 fail_timeout=5s;
            }
            server {
                listen     80;
                proxy_pass rancher_servers_http;
            }

            upstream rancher_servers_https {
                least_conn;
                server <IP_NODE_1>:443 max_fails=3 fail_timeout=5s;
                server <IP_NODE_2>:443 max_fails=3 fail_timeout=5s;
                server <IP_NODE_3>:443 max_fails=3 fail_timeout=5s;
            }
            server {
                listen     443;
                proxy_pass rancher_servers_https;
            }
        }

      3. Save nginx.conf to your load balancer at the following path: /etc/nginx/nginx.conf.

      4. Load the updates to your NGINX configuration by running the following command:

        # nginx -s reload

      Option - Run NGINX as Docker container​

      Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited Example NGINX config as /etc/nginx.conf and run the following command to launch the NGINX container:

      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /etc/nginx.conf:/etc/nginx/nginx.conf \
        nginx:1.14
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nlb.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nlb.html index 3d775570d5d..95e3df6e039 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nlb.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/create-nodes-lb/nlb.html @@ -5,7 +5,7 @@ Amazon NLB | Rancher Manager - + @@ -15,7 +15,7 @@

      Click Create target group to create the second target group, regarding TCP port 80.

      Target Group (TCP port 80)​

      Configure the second target group according to the table below. Screenshots of the configuration are shown just below the table.

      OptionSetting
      Target Group Namerancher-tcp-80
      ProtocolTCP
      Port80
      Target typeinstance
      VPCChoose your VPC
      Protocol
      (Health Check)      		HTTP
      Path
      (Health Check)      		/healthz
      Port (Advanced health check)traffic port
      Healthy threshold (Advanced health)3
      Unhealthy threshold (Advanced)3
      Timeout (Advanced)6 seconds
      Interval (Advanced)10 second
      Success codes200-399

      Screenshot Target group TCP port 80 settings

      Screenshot Target group TCP port 80 Advanced settings

      Register Targets​

      Next, add your Linux nodes to both target groups.

      Select the target group named rancher-tcp-443, click the tab Targets and choose Edit.

      Select the instances (Linux nodes) you want to add, and click Add to registered.

      Screenshot Add targets to target group TCP port 443

      Screenshot Added targets to target group TCP port 443

      When the instances are added, click Save on the bottom right of the screen.

      Repeat those steps, replacing rancher-tcp-443 with rancher-tcp-80. The same instances need to be added as targets to this target group.

      Create Your NLB​

      Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in Create Target Groups.

      1. From your web browser, navigate to the Amazon EC2 Console.

      2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

      3. Click Create Load Balancer.

      4. Choose Network Load Balancer and click Create.

      5. Complete the Step 1: Configure Load Balancer form.

        • Basic Configuration

          • Name: rancher

          • Scheme: internal or internet-facing

            The Scheme that you choose for your NLB is dependent on the configuration of your instances/VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to internal rather than internet-facing.

        • Listeners

          Add the Load Balancer Protocols and Load Balancer Ports below.

          • TCP: 443

        • Availability Zones

          • Select Your VPC and Availability Zones.

      6. Complete the Step 2: Configure Routing form.

        • From the Target Group drop-down, choose Existing target group.

        • From the Name drop-down, choose rancher-tcp-443.

        • Open Advanced health check settings, and configure Interval to 10 seconds.

      7. Complete Step 3: Register Targets. Since you registered your targets earlier, all you have to do is click Next: Review.

      8. Complete Step 4: Review. Look over the load balancer details and click Create when you're satisfied.

      9. After AWS creates the NLB, click Close.

      Add listener to NLB for TCP port 80​

      1. Select your newly created NLB and select the Listeners tab.

      2. Click Add listener.

      3. Use TCP:80 as Protocol : Port

      4. Click Add action and choose Forward to...

      5. From the Forward to drop-down, choose rancher-tcp-80.

      6. Click Save in the top right of the screen.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-init/troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-init/troubleshooting.html index ee77515651f..7cad2b09dd6 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-init/troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-init/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
      Version: v2.0-v2.4

      Troubleshooting

      Helm commands show forbidden​

      When Helm is initiated in the cluster without specifying the correct ServiceAccount, the command helm init will succeed but you won't be able to execute most of the other helm commands. The following error will be shown:

      Error: configmaps is forbidden: User "system:serviceaccount:kube-system:default" cannot list configmaps in the namespace "kube-system"

      To resolve this, the server component (tiller) needs to be removed and added with the correct ServiceAccount. You can use helm reset --force to remove the tiller from the cluster. Please check if it is removed using helm version --server.

      helm reset --force
      Tiller (the Helm server-side component) has been uninstalled from your Kubernetes Cluster.
      helm version --server
      Error: could not find tiller

      When you have confirmed that tiller has been removed, please follow the steps provided in Initialize Helm (Install tiller) to install tiller with the correct ServiceAccount.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/chart-options.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/chart-options.html index 3bd490c7497..b496f8147b1 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/chart-options.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/chart-options.html @@ -5,13 +5,13 @@ Chart Options | Rancher Manager - +
      Version: v2.0-v2.4

      Chart Options

      Common Options​

      OptionDefault ValueDescription
      hostname" "string - the Fully Qualified Domain Name for your Rancher Server
      ingress.tls.source"rancher"string - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret"
      letsEncrypt.email" "string - Your email address
      letsEncrypt.environment"production"string - Valid options: "staging, production"
      privateCAfalsebool - Set to true if your cert is signed by a private CA

      Advanced Options​

      OptionDefault ValueDescription
      additionalTrustedCAsfalsebool - See Additional Trusted CAs
      addLocal"auto"string - Have Rancher detect and import the local Rancher server cluster
      antiAffinity"preferred"string - AntiAffinity rule for Rancher pods - "preferred, required"
      auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
      auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
      auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
      auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
      auditLog.maxBackups1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
      auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
      busyboxImage"busybox"string - Image location for busybox image used to collect audit logs Note: Available as of v2.2.0
      debugfalsebool - set debug flag on rancher server
      extraEnv[]list - set additional environment variables for Rancher Note: Available as of v2.2.0
      imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
      ingress.extraAnnotations{}map - additional annotations to customize the ingress
      ingress.configurationSnippet""string - Add additional Nginx configuration. Can be used for proxy configuration. Note: Available as of v2.0.15, v2.1.10 and v2.2.4
      proxy""string - HTTP[S] proxy server for Rancher
      noProxy"127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"string - comma separated list of hostnames or ip address not to use the proxy
      resources{}map - rancher pod resource requests & limits
      rancherImage"rancher/rancher"string - rancher image source
      rancherImageTagsame as chart versionstring - rancher/rancher image tag
      tls"ingress"string - See External TLS Termination for details. - "ingress, external"
      systemDefaultRegistry""string - private registry to be used for all system Docker images, e.g., http://registry.example.com/ Available as of v2.3.0
      useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations. Available as of v2.3.0

      API Audit Log​

      Enabling the API Audit Log.

      You can collect this log as you would any container log. Enable the Logging service under Rancher Tools for the System Project on the Rancher server cluster.

      --set auditLog.level=1

      By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (rancher-audit-log) will stream the log to stdout. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the hostPath, maxAge, maxBackups, and maxSize options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable the Logging service under Rancher Tools for the Rancher server cluster or System Project.

      Set the auditLog.destination to hostPath to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to hostPath you may want to adjust the other auditLog parameters for log rotation.

      Setting Extra Environment Variables​

      Available as of v2.2.0

      You can set extra environment variables for Rancher server using extraEnv. This list uses the same name and value keys as the container manifest definitions. Remember to quote the values.

      --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
      --set 'extraEnv[0].value=1.0'

      TLS settings​

      Available as of v2.2.0

      To set a different TLS configuration, you can use the CATTLE_TLS_MIN_VERSION and CATTLE_TLS_CIPHERS environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:

      --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
      --set 'extraEnv[0].value=1.0'

      See TLS settings for more information and options.

      Import local Cluster​

      By default Rancher server will detect and import the local cluster it's running on. User with access to the local cluster will essentially have "root" access to all the clusters managed by Rancher server.

      If this is a concern in your environment you can set this option to "false" on your initial install.

      Note: This option is only effective on the initial Rancher install. See Issue 16522 for more information.

      --set addLocal="false"

      Customizing your Ingress​

      To customize or use a different ingress with Rancher server you can set your own Ingress annotations.

      Example on setting a custom certificate issuer:

      --set ingress.extraAnnotations.'certmanager\.k8s\.io/cluster-issuer'=ca-key-pair

      Available as of v2.0.15, v2.1.10 and v2.2.4

      Example on setting a static proxy header with ingress.configurationSnippet. This value is parsed like a template so variables can be used.

      --set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};'

      HTTP Proxy​

      Rancher requires internet access for some functionality (helm charts). Use proxy to set your proxy server.

      Add your IP exceptions to the noProxy list. Make sure you add the Service cluster IP range (default: 10.43.0.1/16) and any worker cluster controlplane nodes. Rancher supports CIDR notation ranges in this list.

      --set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
      --set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16"

      Additional Trusted CAs​

      If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.

      --set additionalTrustedCAs=true

      Once the Rancher deployment is created, copy your CA certs in pem format into a file named ca-additional.pem and use kubectl to create the tls-ca-additional secret in the cattle-system namespace.

      kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem

      Private Registry and Air Gap Installs​

      For details on installing Rancher with a private registry, see:

      External TLS Termination​

      We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

      You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the --set tls=external option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.

      Note: If you are using a Private CA signed certificate, add --set privateCA=true and see Adding TLS Secrets - Using a Private CA Signed Certificate to add the CA cert for Rancher.

      Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

      Configuring Ingress for External TLS when Using NGINX v0.25​

      In NGINX v0.25, the behavior of NGINX has changed regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the cluster.yml to enable the use-forwarded-headers option for ingress:

      ingress:
        provider: nginx
        options:
          use-forwarded-headers: "true"

      Required Headers​

      • Host
      • X-Forwarded-Proto
      • X-Forwarded-Port
      • X-Forwarded-For
      • Read Timeout: 1800 seconds
      • Write Timeout: 1800 seconds
      • Connect Timeout: 30 seconds

      Health Checks​

      Rancher will respond 200 to health checks on the /healthz endpoint.

      Example NGINX config​

      This NGINX configuration is tested on NGINX 1.14.

      Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

      • Replace IP_NODE1, IP_NODE2 and IP_NODE3 with the IP addresses of the nodes in your cluster.
      • Replace both occurrences of FQDN to the DNS name for Rancher.
      • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
      worker_processes 4;
      worker_rlimit_nofile 40000;

      events {
          worker_connections 8192;
      }

      http {
          upstream rancher {
              server IP_NODE_1:80;
              server IP_NODE_2:80;
              server IP_NODE_3:80;
          }

          map $http_upgrade $connection_upgrade {
              default Upgrade;
              ''      close;
          }

          server {
              listen 443 ssl http2;
              server_name FQDN;
              ssl_certificate /certs/fullchain.pem;
              ssl_certificate_key /certs/privkey.pem;

              location / {
                  proxy_set_header Host $host;
                  proxy_set_header X-Forwarded-Proto $scheme;
                  proxy_set_header X-Forwarded-Port $server_port;
                  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                  proxy_pass http://rancher;
                  proxy_http_version 1.1;
                  proxy_set_header Upgrade $http_upgrade;
                  proxy_set_header Connection $connection_upgrade;
                  # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                  proxy_read_timeout 900s;
                  proxy_buffering off;
              }
          }

          server {
              listen 80;
              server_name FQDN;
              return 301 https://$server_name$request_uri;
          }
      }
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/tls-secrets.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/tls-secrets.html index b3f89265916..4a8576d8d57 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/tls-secrets.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/tls-secrets.html @@ -5,13 +5,13 @@ Adding Kubernetes TLS Secrets | Rancher Manager - +
      Version: v2.0-v2.4

      Adding Kubernetes TLS Secrets

      Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the tls-rancher-ingress secret in the cattle-system namespace with the certificate and key.

      Combine the server certificate followed by any intermediate certificate(s) needed into a file named tls.crt. Copy your certificate key into a file named tls.key.

      Use kubectl with the tls secret type to create the secrets.

      kubectl -n cattle-system create secret tls tls-rancher-ingress \
        --cert=tls.crt \
        --key=tls.key

      Note: If you want to replace the certificate, you can delete the tls-rancher-ingress secret using kubectl -n cattle-system delete secret tls-rancher-ingress and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.

      Using a Private CA Signed Certificate​

      If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.

      Copy the CA certificate into a file named cacerts.pem and use kubectl to create the tls-ca secret in the cattle-system namespace.

      Important: Make sure the file is called cacerts.pem as Rancher uses that filename to configure the CA certificate.

      kubectl -n cattle-system create secret generic tls-ca \
        --from-file=cacerts.pem
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/troubleshooting.html index 8db52a86108..be8d8639488 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm-rancher/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
      Version: v2.0-v2.4

      Troubleshooting

      Where is everything​

      Most of the troubleshooting will be done on objects in these 3 namespaces.

      • cattle-system - rancher deployment and pods.
      • ingress-nginx - Ingress controller pods and services.
      • kube-system - tiller and cert-manager pods.

      "default backend - 404"​

      A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration.

      Things to check

      Is Rancher Running​

      Use kubectl to check the cattle-system system namespace and see if the Rancher pods are in a Running state.

      kubectl -n cattle-system get pods

      NAME                           READY     STATUS    RESTARTS   AGE
      pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

      If the state is not Running, run a describe on the pod and check the Events.

      kubectl -n cattle-system describe pod

      ...
      Events:
        Type     Reason                 Age   From                Message
        ----     ------                 ----  ----                -------
        Normal   Scheduled              11m   default-scheduler   Successfully assigned rancher-784d94f59b-vgqzh to localhost
        Normal   SuccessfulMountVolume  11m   kubelet, localhost  MountVolume.SetUp succeeded for volume "rancher-token-dj4mt"
        Normal   Pulling                11m   kubelet, localhost  pulling image "rancher/rancher:v2.0.4"
        Normal   Pulled                 11m   kubelet, localhost  Successfully pulled image "rancher/rancher:v2.0.4"
        Normal   Created                11m   kubelet, localhost  Created container
        Normal   Started                11m   kubelet, localhost  Started container

      Checking the rancher logs​

      Use kubectl to list the pods.

      kubectl -n cattle-system get pods

      NAME                           READY     STATUS    RESTARTS   AGE
      pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

      Use kubectl and the pod name to list the logs from the pod.

      kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh

      Cert CN is "Kubernetes Ingress Controller Fake Certificate"​

      Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert.

      Note: if you are using LetsEncrypt to issue certs it can sometimes take a few minuets to issue the cert.

      cert-manager issued certs (Rancher Generated or LetsEncrypt)​

      cert-manager has 3 parts.

      • cert-manager pod in the kube-system namespace.
      • Issuer object in the cattle-system namespace.
      • Certificate object in the cattle-system namespace.

      Work backwards and do a kubectl describe on each object and check the events. You can track down what might be missing.

      For example there is a problem with the Issuer:

      kubectl -n cattle-system describe certificate
      ...
      Events:
        Type     Reason          Age                 From          Message
        ----     ------          ----                ----          -------
        Warning  IssuerNotReady  18s (x23 over 19m)  cert-manager  Issuer rancher not ready
      kubectl -n cattle-system describe issuer
      ...
      Events:
        Type     Reason         Age                 From          Message
        ----     ------         ----                ----          -------
        Warning  ErrInitIssuer  19m (x12 over 19m)  cert-manager  Error initializing issuer: secret "tls-rancher" not found
        Warning  ErrGetKeyPair  9m (x16 over 19m)   cert-manager  Error getting keypair for CA issuer: secret "tls-rancher" not found

      Bring Your Own SSL Certs​

      Your certs get applied directly to the Ingress object in the cattle-system namespace.

      Check the status of the Ingress object and see if its ready.

      kubectl -n cattle-system describe ingress

      If its ready and the SSL is still not working you may have a malformed cert or secret.

      Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.

      kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller
      ...
      W0705 23:04:58.240571       7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found

      no matches for kind "Issuer"​

      The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown:

      Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1"

      Install cert-manager and try installing Rancher again.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/kubernetes-rke/troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/kubernetes-rke/troubleshooting.html index 59f9c3d71cc..51acd2b9694 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/kubernetes-rke/troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/kubernetes-rke/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
      Version: v2.0-v2.4

      Troubleshooting

      canal Pods show READY 2/3​

      The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups.

      Once the network issue is resolved, the canal pods should timeout and restart to establish their connections.

      nginx-ingress-controller Pods show RESTARTS​

      The most common cause of this issue is the canal pods have failed to establish the overlay network. See canal Pods show READY 2/3 for troubleshooting.

      Failed to set up SSH tunneling for host [xxx.xxx.xxx.xxx]: Can't retrieve Docker Info​

      Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)​

      • User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command docker ps:
      $ ssh user@server
      user@server$ docker ps
      CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES

      See Manage Docker as a non-root user how to set this up properly.

      • When using RedHat/CentOS as operating system, you cannot use the user root to connect to the nodes because of Bugzilla #1527565. You will need to add a separate user and configure it to access the Docker socket. See Manage Docker as a non-root user how to set this up properly.

      • SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using sshd -V on the host you are connecting to, or using netcat:

      $ nc xxx.xxx.xxx.xxx 22
      SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10

      Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: no key found​

      • The key file specified as ssh_key_path cannot be accessed. Make sure that you specified the private key file (not the public key, .pub), and that the user that is running the rke command can access the private key file.

      Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain​

      • The key file specified as ssh_key_path is not correct for accessing the node. Double-check if you specified the correct ssh_key_path for the node and if you specified the correct user to connect with.

      Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: cannot decode encrypted private keys​

      • If you want to use encrypted private keys, you should use ssh-agent to load your keys with your passphrase. If the SSH_AUTH_SOCK environment variable is found in the environment where the rke command is run, it will be used automatically to connect to the node.

      Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?​

      • The node is not reachable on the configured address and port.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/api-auditing.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/api-auditing.html index 9a3c945b0ec..fdf8f210d2b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/api-auditing.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/api-auditing.html @@ -5,13 +5,13 @@ Enable API Auditing | Rancher Manager - +
      Version: v2.0-v2.4

      Enable API Auditing

      Important: RKE add-on install is only supported up to Rancher v2.0.8

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      If you're using RKE to install Rancher, you can use directives to enable API Auditing for your Rancher install. You can know what happened, when it happened, who initiated it, and what cluster it affected. API auditing records all requests and responses to and from the Rancher API, which includes use of the Rancher UI and any other use of the Rancher API through programmatic use.

      In-line Arguments​

      Enable API Auditing using RKE by adding arguments to your Rancher container.

      To enable API auditing:

      • Add API Auditing arguments (args) to your Rancher container.
      • Declare a mountPath in the volumeMounts directive of the container.
      • Declare a path in the volumes directive.

      For more information about each argument, its syntax, and how to view API Audit logs, see Rancher v2.0 Documentation: API Auditing.

      ...
      containers:
              - image: rancher/rancher:latest
                imagePullPolicy: Always
                name: cattle-server
                args: ["--audit-log-path", "/var/log/auditlog/rancher-api-audit.log", "--audit-log-maxbackup", "5", "--audit-log-maxsize", "50", "--audit-level", "2"]
                ports:
                - containerPort: 80
                  protocol: TCP
                - containerPort: 443
                  protocol: TCP
                volumeMounts:
                - mountPath: /etc/rancher/ssl
                  name: cattle-keys-volume
                  readOnly: true
                - mountPath: /var/log/auditlog
                  name: audit-log-dir
              volumes:
              - name: cattle-keys-volume
                secret:
                  defaultMode: 420
                  secretName: cattle-keys-server
              - name: audit-log-dir
                hostPath:
                  path: /var/log/rancher/auditlog
                  type: Directory
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-4-lb/nlb.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-4-lb/nlb.html index 087e58c1fff..e03c3ba629f 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-4-lb/nlb.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-4-lb/nlb.html @@ -5,7 +5,7 @@ Amazon NLB Configuration | Rancher Manager - + @@ -15,7 +15,7 @@

      Click Create target group to create the second target group, regarding TCP port 80.

      Target Group (TCP port 80)​

      Configure the second target group according to the table below. Screenshots of the configuration are shown just below the table.

      OptionSetting
      Target Group Namerancher-tcp-80
      ProtocolTCP
      Port80
      Target typeinstance
      VPCChoose your VPC
      Protocol
      (Health Check)      		HTTP
      Path
      (Health Check)      		/healthz
      Port (Advanced health check)traffic port
      Healthy threshold (Advanced health)3
      Unhealthy threshold (Advanced)3
      Timeout (Advanced)6 seconds
      Interval (Advanced)10 second
      Success codes200-399

      Screenshot Target group TCP port 80 settings

      Screenshot Target group TCP port 80 Advanced settings

      Register Targets​

      Next, add your Linux nodes to both target groups.

      Select the target group named rancher-tcp-443, click the tab Targets and choose Edit.

      Select the instances (Linux nodes) you want to add, and click Add to registered.

      Screenshot Add targets to target group TCP port 443

      Screenshot Added targets to target group TCP port 443

      When the instances are added, click Save on the bottom right of the screen.

      Repeat those steps, replacing rancher-tcp-443 with rancher-tcp-80. The same instances need to be added as targets to this target group.

      Create Your NLB​

      Use Amazon's Wizard to create an Network Load Balancer. As part of this process, you'll add the target groups you created in Create Target Groups.

      1. From your web browser, navigate to the Amazon EC2 Console.

      2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

      3. Click Create Load Balancer.

      4. Choose Network Load Balancer and click Create.

      5. Complete the Step 1: Configure Load Balancer form.

        • Basic Configuration

          • Name: rancher
          • Scheme: internet-facing

        • Listeners

          Add the Load Balancer Protocols and Load Balancer Ports below.

          • TCP: 443

        • Availability Zones

          • Select Your VPC and Availability Zones.

      6. Complete the Step 2: Configure Routing form.

        • From the Target Group drop-down, choose Existing target group.

        • From the Name drop-down, choose rancher-tcp-443.

        • Open Advanced health check settings, and configure Interval to 10 seconds.

      7. Complete Step 3: Register Targets. Since you registered your targets earlier, all you have to do is click Next: Review.

      8. Complete Step 4: Review. Look over the load balancer details and click Create when you're satisfied.

      9. After AWS creates the NLB, click Close.

      Add listener to NLB for TCP port 80​

      1. Select your newly created NLB and select the Listeners tab.

      2. Click Add listener.

      3. Use TCP:80 as Protocol : Port

      4. Click Add action and choose Forward to...

      5. From the Forward to drop-down, choose rancher-tcp-80.

      6. Click Save in the top right of the screen.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/alb.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/alb.html index f1bd134c109..31b3cf82b0a 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/alb.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/alb.html @@ -5,13 +5,13 @@ Amazon ALB Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      Amazon ALB Configuration

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher helm chart to install Kubernetes Rancher. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Objectives​

      Configuring an Amazon ALB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.

      1. Create Target Group

        Begin by creating one target group for the http protocol. You'll add your Linux nodes to this group.

      2. Register Targets

        Add your Linux nodes to the target group.

      3. Create Your ALB

        Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target groups you created in 1. Create Target Groups.

      Create Target Group​

      Your first ALB configuration step is to create one target group for HTTP.

      Log into the Amazon AWS Console to get started.

      The document below will guide you through this process. Use the data in the tables below to complete the procedure.

      Amazon Documentation: Create a Target Group

      Target Group (HTTP)​

      OptionSetting
      Target Group Namerancher-http-80
      ProtocolHTTP
      Port80
      Target typeinstance
      VPCChoose your VPC
      Protocol
      (Health Check)      		HTTP
      Path
      (Health Check)      		/healthz

      Register Targets​

      Next, add your Linux nodes to your target group.

      Amazon Documentation: Register Targets with Your Target Group

      Create Your ALB​

      Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add the target group you created in Create Target Group.

      1. From your web browser, navigate to the Amazon EC2 Console.

      2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

      3. Click Create Load Balancer.

      4. Choose Application Load Balancer.

      5. Complete the Step 1: Configure Load Balancer form.

        • Basic Configuration

          • Name: rancher-http
          • Scheme: internet-facing
          • IP address type: ipv4

        • Listeners

          Add the Load Balancer Protocols and Load Balancer Ports below.

          • HTTP: 80
          • HTTPS: 443

        • Availability Zones

          • Select Your VPC and Availability Zones.

      6. Complete the Step 2: Configure Security Settings form.

        Configure the certificate you want to use for SSL termination.

      7. Complete the Step 3: Configure Security Groups form.

      8. Complete the Step 4: Configure Routing form.

        • From the Target Group drop-down, choose Existing target group.

        • Add target group rancher-http-80.

      9. Complete Step 5: Register Targets. Since you registered your targets earlier, all you have to do it click Next: Review.

      10. Complete Step 6: Review. Look over the load balancer details and click Create when you're satisfied.

      11. After AWS creates the ALB, click Close.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/nginx.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/nginx.html index 7da2739c3cd..3ac852a5d93 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/nginx.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/layer-7-lb/nginx.html @@ -5,13 +5,13 @@ NGINX Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      NGINX Configuration

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Install NGINX​

      Start by installing NGINX on your load balancer host. NGINX has packages available for all known operating systems.

      For help installing NGINX, refer to their install documentation.

      Create NGINX Configuration​

      See Example NGINX config.

      Run NGINX​

      • Reload or restart NGINX

        # Reload NGINX
        nginx -s reload

        # Restart NGINX
        # Depending on your Linux distribution
        service nginx restart
        systemctl restart nginx

      Browse to Rancher UI​

      You should now be to able to browse to https://FQDN.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/proxy.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/proxy.html index 5f11bb0f6ba..b4b0dfc47d5 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/proxy.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/proxy.html @@ -5,13 +5,13 @@ HTTP Proxy Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      HTTP Proxy Configuration

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.

      Make sure NO_PROXY contains the network addresses, network address ranges and domains that should be excluded from using the proxy.

      Environment variablePurpose
      HTTP_PROXYProxy address to use when initiating HTTP connection(s)
      HTTPS_PROXYProxy address to use when initiating HTTPS connection(s)
      NO_PROXYNetwork address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s)

      Note NO_PROXY must be in uppercase to use network range (CIDR) notation.

      Kubernetes installation​

      When using Kubernetes installation, the environment variables need to be added to the RKE Config File template.

      The environment variables should be defined in the Deployment inside the RKE Config File Template. You only have to add the part starting with env: to (but not including) ports:. Make sure the indentation is identical to the preceding name:. Required values for NO_PROXY are:

      • localhost
      • 127.0.0.1
      • 0.0.0.0
      • Configured service_cluster_ip_range (default: 10.43.0.0/16)

      The example below is based on a proxy server accessible at http://192.168.0.1:3128, and excluding usage of the proxy when accessing network range 192.168.10.0/24, the configured service_cluster_ip_range (10.43.0.0/16) and every hostname under the domain example.com. If you have changed the service_cluster_ip_range, you have to update the value below accordingly.

      ...
      ---
        kind: Deployment
        apiVersion: extensions/v1beta1
        metadata:
          namespace: cattle-system
          name: cattle
        spec:
          replicas: 1
          template:
            metadata:
              labels:
                app: cattle
            spec:
              serviceAccountName: cattle-admin
              containers:
              - image: rancher/rancher:latest
                imagePullPolicy: Always
                name: cattle-server
                env:
                - name: HTTP_PROXY
                  value: "http://192.168.10.1:3128"
                - name: HTTPS_PROXY
                  value: "http://192.168.10.1:3128"
                - name: NO_PROXY
                  value: "localhost,127.0.0.1,0.0.0.0,10.43.0.0/16,192.168.10.0/24,example.com"
                ports:
      ...
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/default-backend.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/default-backend.html index 36ef38a536d..50b20d1d1f0 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/default-backend.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/default-backend.html @@ -5,13 +5,13 @@ 404 - default backend | Rancher Manager - +
      Version: v2.0-v2.4

      404 - default backend

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      To debug issues around this error, you will need to download the command-line tool kubectl. See Install and Set Up kubectl how to download kubectl for your platform.

      When you have made changes to rancher-cluster.yml, you will have to run rke remove --config rancher-cluster.yml to clean the nodes, so it cannot conflict with previous configuration errors.

      Possible causes​

      The nginx ingress controller is not able to serve the configured host in rancher-cluster.yml. This should be the FQDN you configured to access Rancher. You can check if it is properly configured by viewing the ingress that is created by running the following command:

      kubectl --kubeconfig kube_config_rancher-cluster.yml get ingress -n cattle-system -o wide

      Check if the HOSTS column is displaying the FQDN you configured in the template, and that the used nodes are listed in the ADDRESS column. If that is configured correctly, we can check the logging of the nginx ingress controller.

      The logging of the nginx ingress controller will show why it cannot serve the requested host. To view the logs, you can run the following command

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=ingress-nginx -n ingress-nginx
      Errors
      • x509: certificate is valid for fqdn, not your_configured_fqdn

      The used certificates do not contain the correct hostname. Generate new certificates that contain the chosen FQDN to access Rancher and redeploy.

      • Port 80 is already in use. Please check the flag --http-port

      There is a process on the node occupying port 80, this port is needed for the nginx ingress controller to route requests to Rancher. You can find the process by running the command: netstat -plant | grep \:80.

      Stop/kill the process and redeploy.

      • unexpected error creating pem file: no valid PEM formatted block found

      The base64 encoded string configured in the template is not valid. Please check if you can decode the configured string using base64 -D STRING, this should return the same output as the content of the file you used to generate the string. If this is correct, please check if the base64 encoded string is placed directly after the key, without any newlines before, in between or after. (For example: tls.crt: LS01..)

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/generic-troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/generic-troubleshooting.html index d4ff285fdc4..be741b25c1f 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/generic-troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/generic-troubleshooting.html @@ -5,13 +5,13 @@ Generic troubleshooting | Rancher Manager - +
      Version: v2.0-v2.4

      Generic troubleshooting

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Below are steps that you can follow to determine what is wrong in your cluster.

      Double check if all the required ports are opened in your (host) firewall​

      Double check if all the required ports are opened in your (host) firewall.

      All nodes should be present and in Ready state​

      To check, run the command:

      kubectl --kubeconfig kube_config_rancher-cluster.yml get nodes

      If a node is not shown in this output or a node is not in Ready state, you can check the logging of the kubelet container. Login to the node and run docker logs kubelet.

      All pods/jobs should be in Running/Completed state​

      To check, run the command:

      kubectl --kubeconfig kube_config_rancher-cluster.yml get pods --all-namespaces

      If a pod is not in Running state, you can dig into the root cause by running:

      Describe pod​

      kubectl --kubeconfig kube_config_rancher-cluster.yml describe pod POD_NAME -n NAMESPACE

      Pod container logs​

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs POD_NAME -n NAMESPACE

      If a job is not in Completed state, you can dig into the root cause by running:

      Describe job​

      kubectl --kubeconfig kube_config_rancher-cluster.yml describe job JOB_NAME -n NAMESPACE

      Logs from the containers of pods of the job​

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l job-name=JOB_NAME -n NAMESPACE

      Check ingress​

      Ingress should have the correct HOSTS (showing the configured FQDN) and ADDRESS (address(es) it will be routed to).

      kubectl --kubeconfig kube_config_rancher-cluster.yml get ingress --all-namespaces

      List all Kubernetes cluster events​

      Kubernetes cluster events are stored, and can be retrieved by running:

      kubectl --kubeconfig kube_config_rancher-cluster.yml get events --all-namespaces

      Check Rancher container logging​

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=cattle -n cattle-system

      Check NGINX ingress controller logging​

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l app=ingress-nginx -n ingress-nginx

      Check if overlay network is functioning correctly​

      The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from NODE_1 to NODE_2. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.

      To test the overlay network, you can launch the following DaemonSet definition. This will run an alpine container on every host, which we will use to run a ping test between containers on all hosts.

      1. Save the following file as ds-alpine.yml

        apiVersion: apps/v1
        kind: DaemonSet
        metadata:
          name: alpine
        spec:
          selector:
              matchLabels:
                name: alpine
          template:
            metadata:
              labels:
                name: alpine
            spec:
              tolerations:
              - effect: NoExecute
                key: "node-role.kubernetes.io/etcd"
                value: "true"
              - effect: NoSchedule
                key: "node-role.kubernetes.io/controlplane"
                value: "true"
              containers:
              - image: alpine
                imagePullPolicy: Always
                name: alpine
                command: ["sh", "-c", "tail -f /dev/null"]
                terminationMessagePath: /dev/termination-log

      2. Launch it using kubectl --kubeconfig kube_config_rancher-cluster.yml create -f ds-alpine.yml

      3. Wait until kubectl --kubeconfig kube_config_rancher-cluster.yml rollout status ds/alpine -w returns: daemon set "alpine" successfully rolled out.

      4. Run the following command to let each container on every host ping each other (it's a single line command).

        echo "=> Start"; kubectl --kubeconfig kube_config_rancher-cluster.yml get pods -l name=alpine -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' | while read spod shost; do kubectl --kubeconfig kube_config_rancher-cluster.yml get pods -l name=alpine -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' | while read tip thost; do kubectl --kubeconfig kube_config_rancher-cluster.yml --request-timeout='10s' exec $spod -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $shost cannot reach $thost; fi; done; done; echo "=> End"

      5. When this command has finished running, the output indicating everything is correct is:

        => Start
        => End

      If you see error in the output, that means that the required ports for overlay networking are not opened between the hosts indicated.

      Example error output of a situation where NODE1 had the UDP ports blocked.

      => Start
      command terminated with exit code 1
      NODE2 cannot reach NODE1
      command terminated with exit code 1
      NODE3 cannot reach NODE1
      command terminated with exit code 1
      NODE1 cannot reach NODE2
      command terminated with exit code 1
      NODE1 cannot reach NODE3
      => End
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/job-complete-status.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/job-complete-status.html index d7c3b4901ff..c725f032b9c 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/job-complete-status.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/rke-add-on/troubleshooting/job-complete-status.html @@ -5,13 +5,13 @@ Failed to get job complete status | Rancher Manager - +
      Version: v2.0-v2.4

      Failed to get job complete status

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      To debug issues around this error, you will need to download the command-line tool kubectl. See Install and Set Up kubectl how to download kubectl for your platform.

      When you have made changes to rancher-cluster.yml, you will have to run rke remove --config rancher-cluster.yml to clean the nodes, so it cannot conflict with previous configuration errors.

      Failed to deploy addon execute job [rke-user-includes-addons]: Failed to get job complete status​

      Something is wrong in the addons definitions, you can run the following command to get the root cause in the logging of the job:

      kubectl --kubeconfig kube_config_rancher-cluster.yml logs -l job-name=rke-user-addon-deploy-job -n kube-system

      error: error converting YAML to JSON: yaml: line 9:​

      The structure of the addons definition in rancher-cluster.yml is wrong. In the different resources specified in the addons section, there is a error in the structure of the YAML. The pointer yaml line 9 references to the line number of the addon that is causing issues.

      Things to check
        • Is each of the base64 encoded certificate string placed directly after the key, for example: `tls.crt: LS01...`, there should be no newline/space before, in between or after.
        • Is the YAML properly formatted, each indentation should be 2 spaces as shown in the template files.
        • Verify the integrity of your certificate by running this command `cat MyCertificate | base64 -d` on Linux, `cat MyCertificate | base64 -D` on Mac OS . If any error exists, the command output will tell you.

      Error from server (BadRequest): error when creating "/etc/config/rke-user-addon.yaml": Secret in version "v1" cannot be handled as a Secret​

      The base64 string of one of the certificate strings is wrong. The log message will try to show you what part of the string is not recognized as valid base64.

      Things to check
        • Check if the base64 string is valid by running one of the commands below:
          • # MacOS
          echo BASE64_CRT | base64 -D
          # Linux
          echo BASE64_CRT | base64 -d
          # Windows
          certutil -decode FILENAME.base64 FILENAME.verify

      The Ingress "cattle-ingress-http" is invalid: spec.rules[0].host: Invalid value: "IP": must be a DNS name, not an IP address​

      The host value can only contain a host name, as it is needed by the ingress controller to match the hostname and pass to the correct backend.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html index da7d282f2ff..4bff28a694f 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html @@ -5,13 +5,13 @@ Opening Ports with firewalld | Rancher Manager - +
      Version: v2.0-v2.4

      Opening Ports with firewalld

      We recommend disabling firewalld. For Kubernetes 1.19.x and higher, firewalld must be turned off.

      Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm.

      For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller:

      Chain INPUT (policy ACCEPT)
      target     prot opt source               destination
      ACCEPT     all  --  anywhere             anywhere             state RELATED,ESTABLISHED
      ACCEPT     icmp --  anywhere             anywhere
      ACCEPT     all  --  anywhere             anywhere
      ACCEPT     tcp  --  anywhere             anywhere             state NEW tcp dpt:ssh
      REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

      Chain FORWARD (policy ACCEPT)
      target     prot opt source               destination
      REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

      Chain OUTPUT (policy ACCEPT)
      target     prot opt source               destination

      You can check the default firewall rules with this command:

      sudo iptables --list

      This section describes how to use firewalld to apply the firewall port rules for nodes in a high-availability Rancher server cluster.

      Prerequisite

      Install v7.x or later ofvfirewalld:

      yum install firewalld
      systemctl start firewalld
      systemctl enable firewalld

      Applying Firewall Port Rules

      In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:

      firewall-cmd --permanent --add-port=22/tcp
      firewall-cmd --permanent --add-port=80/tcp
      firewall-cmd --permanent --add-port=443/tcp
      firewall-cmd --permanent --add-port=2376/tcp
      firewall-cmd --permanent --add-port=2379/tcp
      firewall-cmd --permanent --add-port=2380/tcp
      firewall-cmd --permanent --add-port=6443/tcp
      firewall-cmd --permanent --add-port=8472/udp
      firewall-cmd --permanent --add-port=9099/tcp
      firewall-cmd --permanent --add-port=10250/tcp
      firewall-cmd --permanent --add-port=10254/tcp
      firewall-cmd --permanent --add-port=30000-32767/tcp
      firewall-cmd --permanent --add-port=30000-32767/udp

      If your Rancher server nodes have separate roles, use the following commands based on the role of the node:

      # For etcd nodes, run the following commands:
      firewall-cmd --permanent --add-port=2376/tcp
      firewall-cmd --permanent --add-port=2379/tcp
      firewall-cmd --permanent --add-port=2380/tcp
      firewall-cmd --permanent --add-port=8472/udp
      firewall-cmd --permanent --add-port=9099/tcp
      firewall-cmd --permanent --add-port=10250/tcp

      # For control plane nodes, run the following commands:
      firewall-cmd --permanent --add-port=80/tcp
      firewall-cmd --permanent --add-port=443/tcp
      firewall-cmd --permanent --add-port=2376/tcp
      firewall-cmd --permanent --add-port=6443/tcp
      firewall-cmd --permanent --add-port=8472/udp
      firewall-cmd --permanent --add-port=9099/tcp
      firewall-cmd --permanent --add-port=10250/tcp
      firewall-cmd --permanent --add-port=10254/tcp
      firewall-cmd --permanent --add-port=30000-32767/tcp
      firewall-cmd --permanent --add-port=30000-32767/udp

      # For worker nodes, run the following commands:
      firewall-cmd --permanent --add-port=22/tcp
      firewall-cmd --permanent --add-port=80/tcp
      firewall-cmd --permanent --add-port=443/tcp
      firewall-cmd --permanent --add-port=2376/tcp
      firewall-cmd --permanent --add-port=8472/udp
      firewall-cmd --permanent --add-port=9099/tcp
      firewall-cmd --permanent --add-port=10250/tcp
      firewall-cmd --permanent --add-port=10254/tcp
      firewall-cmd --permanent --add-port=30000-32767/tcp
      firewall-cmd --permanent --add-port=30000-32767/udp

      After the firewall-cmd commands have been run on a node, use the following command to enable the firewall rules:

      firewall-cmd --reload

      Result: The firewall is updated so that Helm can communicate with the Rancher server nodes.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-4-lb.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-4-lb.html index 24d6d77439c..4cf008d5c41 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-4-lb.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-4-lb.html @@ -5,7 +5,7 @@ Kubernetes Install with External Load Balancer (TCP/Layer 4) | Rancher Manager - + @@ -17,7 +17,7 @@ Create a self-signed certificate.

      • The certificate files must be in PE The base64 encoded string should be on the same line as tls.crt or tls.key, without any newline at the beginning, in between or at the end.

        Step Result: After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

        ---
        apiVersion: v1
        kind: Secret
        metadata:
            name: cattle-keys-ingress
            namespace: cattle-system
        type: Opaque
        data:
            tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
            tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

      • In kind: Secret with name: cattle-keys-server, replace <BASE64_CA> with the base64 encoded string of the CA Certificate file (usually called ca.pem or ca.crt).

        Note: The base64 encoded string should be on the same line as cacerts.pem, without any newline at the beginning, in between or at the end.

        • **Step Result:** The file should look like the example below (the base64 encoded string should be different):

        ```yaml
        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-server
          namespace: cattle-system
        type: Opaque
        data:
          cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
        ```
        Option B—Bring Your Own Certificate: Signed by Recognized CA

        If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the intermediate certificates in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included.

        In the kind: Secret with name: cattle-keys-ingress:

        • Replace <BASE64_CRT> with the base64 encoded string of the Certificate file (usually called cert.pem or domain.crt)
        • Replace <BASE64_KEY> with the base64 encoded string of the Certificate Key file (usually called key.pem or domain.key)

        After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

        Note: The base64 encoded string should be on the same line as tls.crt or tls.key, without any newline at the beginning, in between or at the end.

        ---
        apiVersion: v1
        kind: Secret
        metadata:
          name: cattle-keys-ingress
          namespace: cattle-system
        type: Opaque
        data:
          tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
          tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

        8. Configure FQDN​

        There are two references to <FQDN> in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in Configure DNS.

        In the kind: Ingress with name: cattle-ingress-http:

        After replacing <FQDN> with the FQDN chosen in Configure DNS, the file should look like the example below (rancher.yourdomain.com is the FQDN used in this example):

         ---
          apiVersion: extensions/v1beta1
          kind: Ingress
          metadata:
            namespace: cattle-system
            name: cattle-ingress-http
            annotations:
              nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
              nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
              nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
          spec:
            rules:
            - host: rancher.yourdomain.com
              http:
                paths:
                - backend:
                    serviceName: cattle-service
                    servicePort: 80
            tls:
            - secretName: cattle-keys-ingress
              hosts:
              - rancher.yourdomain.com

        Save the .yml file and close it.

        9. Configure Rancher version​

        The last reference that needs to be replaced is <RANCHER_VERSION>. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the GitHub README. Make sure the version is an actual version number, and not a named tag like stable or latest. The example below shows the version configured to v2.0.6.

              spec:
                serviceAccountName: cattle-admin
                containers:
                - image: rancher/rancher:v2.0.6
                  imagePullPolicy: Always

        10. Back Up Your RKE Config File​

        After you close your .yml file, back it up to a secure location. You can use this file again when it's time to upgrade Rancher.

        11. Run RKE​

        With all configuration in place, use RKE to launch Rancher. You can complete this action by running the rke up command and using the --config parameter to point toward your config file.

        1. From your workstation, make sure rancher-cluster.yml and the downloaded rke binary are in the same directory.

        2. Open a Terminal instance. Change to the directory that contains your config file and rke.

        3. Enter one of the rke up commands listen below.

        rke up --config rancher-cluster.yml

        Step Result: The output should be similar to the snippet below:

        INFO[0000] Building Kubernetes cluster
        INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
        INFO[0000] [network] Deploying port listener containers
        INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
        ...
        INFO[0101] Finished building Kubernetes cluster successfully

        12. Back Up Auto-Generated Config File​

        During installation, RKE automatically generates a config file named kube_config_rancher-cluster.yml in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.

        What's Next?​

        You have a couple of options:


        FAQ and Troubleshooting​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-7-lb.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-7-lb.html index 09d21e52e05..8e6f5bb2206 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-7-lb.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/rke-add-on/layer-7-lb.html @@ -5,14 +5,14 @@ Kubernetes Install with External Load Balancer (HTTPS/Layer 7) | Rancher Manager - +
        Version: v2.0-v2.4

        Kubernetes Install with External Load Balancer (HTTPS/Layer 7)

        Important: RKE add-on install is only supported up to Rancher v2.0.8​

        Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install.

        If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

        This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:

        In an HA setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.

        Rancher installed on a Kubernetes cluster with layer 7 load balancer, depicting SSL termination at load balancer

        Rancher HA

        Installation Outline​

        Installation of Rancher in a high-availability configuration involves multiple procedures. Review this outline to learn about each procedure you need to complete.

        1. Provision Linux Hosts​

        Provision three Linux hosts according to our Requirements.

        2. Configure Load Balancer​

        When using a load balancer in front of Rancher, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header X-Forwarded-Proto: https, this redirect is disabled. This is the expected configuration when terminating SSL externally.

        The load balancer has to be configured to support the following:

        • WebSocket connections
        • SPDY / HTTP/2 protocols
        • Passing / setting the following headers:
        HeaderValueDescription
        HostFQDN used to reach Rancher.To identify the server requested by the client.
        X-Forwarded-ProtohttpsTo identify the protocol that a client used to connect to the load balancer.

        Note: If this header is present, rancher/rancher does not redirect HTTP to HTTPS.
        X-Forwarded-PortPort used to reach Rancher.To identify the protocol that client used to connect to the load balancer.
        X-Forwarded-ForIP of the client connection.To identify the originating IP address of a client.

        Health checks can be executed on the /healthz endpoint of the node, this will return HTTP 200.

        We have example configurations for the following load balancers:

        3. Configure DNS​

        Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., rancher.yourdomain.com).

        1. Log into your DNS server a create a DNS A record that points to the IP address of your load balancer.

        2. Validate that the DNS A is working correctly. Run the following command from any terminal, replacing HOSTNAME.DOMAIN.COM with your chosen FQDN:

          nslookup HOSTNAME.DOMAIN.COM

          Step Result: Terminal displays output similar to the following:

          $ nslookup rancher.yourdomain.com
          Server:         YOUR_HOSTNAME_IP_ADDRESS
          Address:        YOUR_HOSTNAME_IP_ADDRESS#53

          Non-authoritative answer:
          Name:   rancher.yourdomain.com
          Address: HOSTNAME.DOMAIN.COM

        4. Install RKE​

        RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.

        1. Follow the RKE Install instructions.

        2. Confirm that RKE is now executable by running the following command:

          rke --version

        5. Download RKE Config File Template​

        RKE uses a YAML config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.

        1. Download one of following templates, depending on the SSL certificate you're using.

        1. Rename the file to rancher-cluster.yml.

        6. Configure Nodes​

        Once you have the rancher-cluster.yml config file template, edit the nodes section to point toward your Linux hosts.

        1. Open rancher-cluster.yml in your favorite text editor.

        2. Update the nodes section with the information of your Linux hosts.

          For each node in your cluster, update the following placeholders: IP_ADDRESS_X and USER. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run docker ps.

          Note:

          When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See Operating System Requirements for RHEL/CentOS specific requirements.

          nodes:
              # The IP address or hostname of the node
          - address: IP_ADDRESS_1
              # User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
              # When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
              user: USER
              role: [controlplane,etcd,worker]
              # Path the SSH key that can be used to access to node with the specified user
              ssh_key_path: ~/.ssh/id_rsa
          - address: IP_ADDRESS_2
              user: USER
              role: [controlplane,etcd,worker]
              ssh_key_path: ~/.ssh/id_rsa
          - address: IP_ADDRESS_3
              user: USER
              role: [controlplane,etcd,worker]
              ssh_key_path: ~/.ssh/id_rsa

        3. Optional: By default, rancher-cluster.yml is configured to take backup snapshots of your data. To disable these snapshots, change the backup directive setting to false, as depicted below.

          services:
            etcd:
              backup: false

        7. Configure Certificates​

        For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

        Choose from the following options:

        Option A—Bring Your Own Certificate: Self-Signed

        Prerequisites: Create a self-signed certificate.

        • The certificate files must be in PEM format.
        • The certificate files must be encoded in base64.
        • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

        In kind: Secret with name: cattle-keys-ingress, replace <BASE64_CA> with the base64 encoded string of the CA Certificate file (usually called ca.pem or ca.crt)

        Note: The base64 encoded string should be on the same line as cacerts.pem, without any newline at the beginning, in between or at the end.

        After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

            ---
            apiVersion: v1
            kind: Secret
            metadata:
                name: cattle-keys-server
                namespace: cattle-system
            type: Opaque
            data:
                cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
        Option B—Bring Your Own Certificate: Signed by Recognized CA

        If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part.

        8. Configure FQDN​

        There is one reference to <FQDN> in the RKE config file. Replace this reference with the FQDN you chose in 3. Configure DNS.

        1. Open rancher-cluster.yml.

        2. In the kind: Ingress with name: cattle-ingress-http:

          Replace <FQDN> with the FQDN chosen in 3. Configure DNS.

          Step Result: After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

          apiVersion: extensions/v1beta1
            kind: Ingress
            metadata:
              namespace: cattle-system
              name: cattle-ingress-http
              annotations:
                nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
                nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
                nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            spec:
              rules:
              - host: rancher.yourdomain.com
                http:
                  paths:
                  - backend:
                      serviceName: cattle-service
                      servicePort: 80
        1. Save the file and close it.

        9. Configure Rancher version​

        The last reference that needs to be replaced is <RANCHER_VERSION>. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the GitHub README. Make sure the version is an actual version number, and not a named tag like stable or latest. The example below shows the version configured to v2.0.6.

              spec:
                serviceAccountName: cattle-admin
                containers:
                - image: rancher/rancher:v2.0.6
                  imagePullPolicy: Always

        10. Back Up Your RKE Config File​

        After you close your RKE config file, rancher-cluster.yml, back it up to a secure location. You can use this file again when it's time to upgrade Rancher.

        11. Run RKE​

        With all configuration in place, use RKE to launch Rancher. You can complete this action by running the rke up command and using the --config parameter to point toward your config file.

        1. From your workstation, make sure rancher-cluster.yml and the downloaded rke binary are in the same directory.

        2. Open a Terminal instance. Change to the directory that contains your config file and rke.

        3. Enter one of the rke up commands listen below.

          rke up --config rancher-cluster.yml

          Step Result: The output should be similar to the snippet below:

          INFO[0000] Building Kubernetes cluster
          INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
          INFO[0000] [network] Deploying port listener containers
          INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
          ...
          INFO[0101] Finished building Kubernetes cluster successfully

        12. Back Up Auto-Generated Config File​

        During installation, RKE automatically generates a config file named kube_config_rancher-cluster.yml in the same directory as the rancher-cluster.yml file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.

        What's Next?​


        FAQ and Troubleshooting​

        How Do I Know if My Certificates are in PEM Format?

        You can recognize the PEM format by the following traits:

        • The file begins with the following header:
          -----BEGIN CERTIFICATE-----
        • The header is followed by a long string of characters. Like, really long.
        • The file ends with a footer:
          -----END CERTIFICATE-----

        PEM Certificate Example:

        ----BEGIN CERTIFICATE----- MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV ... more lines VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END CERTIFICATE-----

        How Can I Encode My PEM Files in base64?

        To encode your certificates in base64:

        1. Change directory to where the PEM file resides.
        2. Run one of the following commands. Replace FILENAME with the name of your certificate.
          # MacOS cat FILENAME | base64 # Linux cat FILENAME | base64 -w0 # Windows certutil -encode FILENAME FILENAME.base64

        How Can I Verify My Generated base64 String For The Certificates?

        To decode your certificates in base64:

        1. Copy the generated base64 string.
        2. Run one of the following commands. Replace YOUR_BASE64_STRING with the previously copied base64 string.
          # MacOS echo YOUR_BASE64_STRING | base64 -D # Linux echo YOUR_BASE64_STRING | base64 -d # Windows certutil -decode FILENAME.base64 FILENAME.verify

        What is the Order of Certificates if I Want to Add My Intermediate(s)?

        The order of adding certificates is as follows:

        -----BEGIN CERTIFICATE----- %YOUR_CERTIFICATE% -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- %YOUR_INTERMEDIATE_CERTIFICATE% -----END CERTIFICATE-----

        How Do I Validate My Certificate Chain?

        You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. Theca.pem file must be the same as you added to the rancher/rancher container. When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

        Command:

        openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443 -servername rancher.yourdomain.com ... Verify return code: 0 (ok)
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html index f149ef3ea92..0aafd6b57d7 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html @@ -5,13 +5,13 @@ Tuning etcd for Large Installations | Rancher Manager - +
        Version: v2.0-v2.4

        Tuning etcd for Large Installations

        When running larger Rancher installations with 15 or more clusters it is recommended to increase the default keyspace for etcd from the default 2GB. The maximum setting is 8GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval.

        The etcd data set is automatically cleaned up on a five minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see mvcc: database space exceeded errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the quota-backend-bytes setting on the etcd servers.

        Example: This snippet of the RKE cluster.yml file increases the keyspace size to 5GB​

        # RKE cluster.yml
        ---
        services:
          etcd:
            extra_args:
              quota-backend-bytes: 5368709120

        Scaling etcd disk performance​

        You can follow the recommendations from the etcd docs on how to tune the disk priority on the host.

        Additionally, to reduce IO contention on the disks for etcd, you can use a dedicated device for the data and wal directory. Based on etcd best practices, mirroring RAID configurations are unnecessary because etcd replicates data between the nodes in the cluster. You can use striping RAID configurations to increase available IOPS.

        To implement this solution in an RKE cluster, the /var/lib/etcd/data and /var/lib/etcd/wal directories will need to have disks mounted and formatted on the underlying host. In the extra_args directive of the etcd service, you must include the wal_dir directory. Without specifying the wal_dir, etcd process will try to manipulate the underlying wal mount with insufficient permissions.

        # RKE cluster.yml
        ---
        services:
          etcd:
            extra_args:
              data-dir: '/var/lib/rancher/etcd/data/'
              wal-dir: '/var/lib/rancher/etcd/wal/wal_dir'
            extra_binds:
              - '/var/lib/etcd/data:/var/lib/rancher/etcd/data'
              - '/var/lib/etcd/wal:/var/lib/rancher/etcd/wal'
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html index 4c0c46e30eb..8f3233e3cf5 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html @@ -5,13 +5,13 @@ UI for Istio Virtual Services and Destination Rules | Rancher Manager - +
        Version: v2.0-v2.4

        UI for Istio Virtual Services and Destination Rules

        This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.

        Prerequisite: Turning on this feature does not enable Istio. A cluster administrator needs to enable Istio for the cluster in order to use the feature.

        To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

        Environment Variable KeyDefault ValueStatusAvailable as of
        istio-virtual-service-uifalseExperimentalv2.3.0
        istio-virtual-service-uitrueGAv2.3.2

        About this Feature

        A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.

        When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use kubectl to manage traffic with Istio.

        The feature enables two UI tabs: one tab for Virtual Services and another for Destination Rules.

        • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the Istio documentation.
        • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the Istio documentation.

        To see these tabs,

        1. Go to the project view in Rancher and click Resources > Istio.
        2. You will see tabs for Traffic Graph, which has the Kiali network visualization integrated into the UI, and Traffic Metrics, which shows metrics for the success rate and request volume of traffic to your services, among other metrics. Next to these tabs, you should see the tabs for Virtual Services and Destination Rules.
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html index 910fdd5fadb..b1e7355acd9 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html @@ -5,7 +5,7 @@ Running on ARM64 (Experimental) | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        Running on ARM64 (Experimental)

        Important:

        Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment.

        The following options are available when using an ARM64 platform:

        • Running Rancher on ARM64 based node(s)

          • Only for Docker Install. Please note that the following installation command replaces the examples found in the Docker Install link:

            # In the last line `rancher/rancher:vX.Y.Z`, be certain to replace "X.Y.Z" with a released version in which ARM64 builds exist. For  example, if your matching version is v2.5.8, you would fill in this line with `rancher/rancher:v2.5.8`.
            docker run -d --restart=unless-stopped \
              -p 80:80 -p 443:443 \
              --privileged \
              rancher/rancher:vX.Y.Z

            Note: To check if your specific released version is compatible with the ARM64 architecture, you may navigate to your version's release notes in the following two ways:

        • Create custom cluster and adding ARM64 based node(s)

          • Kubernetes cluster version must be 1.12 or higher
          • CNI Network Provider must be Flannel

        • Importing clusters that contain ARM64 based nodes

          • Kubernetes cluster version must be 1.12 or higher

        Please see Cluster Options for information on how to configure the cluster options.

        The following features are not tested:

        • Monitoring, alerts, notifiers, pipelines and logging
        • Launching apps from the catalog
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html index 6d278fc0bc8..b88d4974c72 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html @@ -5,13 +5,13 @@ Allow Unsupported Storage Drivers | Rancher Manager - +
        Version: v2.0-v2.4

        Allow Unsupported Storage Drivers

        This feature allows you to use types for storage providers and provisioners that are not enabled by default.

        To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

        Environment Variable KeyDefault ValueDescription
        unsupported-storage-driversfalseThis feature enables types for storage providers and provisioners that are not enabled by default.

        Types for Persistent Volume Plugins that are Enabled by Default​

        Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

        NamePlugin
        Amazon EBS Diskaws-ebs
        AzureFileazure-file
        AzureDiskazure-disk
        Google Persistent Diskgce-pd
        Longhornflex-volume-longhorn
        VMware vSphere Volumevsphere-volume
        Locallocal
        Network File Systemnfs
        hostPathhost-path

        Types for StorageClass that are Enabled by Default​

        Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

        NamePlugin
        Amazon EBS Diskaws-ebs
        AzureFileazure-file
        AzureDiskazure-disk
        Google Persistent Diskgce-pd
        Longhornflex-volume-longhorn
        VMware vSphere Volumevsphere-volume
        Locallocal
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html index 9e70daf7f2d..944947e5570 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html @@ -5,13 +5,13 @@ Rollbacks | Rancher Manager - +
        Version: v2.0-v2.4

        Rollbacks

        Rolling Back to Rancher v2.2-v2.4​

        For Rancher installed on Kubernetes, follow the procedure detailed here: Restoring Backups for Kubernetes installs. Restoring a snapshot of the Rancher Server cluster will revert Rancher to the version and state at the time of the snapshot.

        For information on how to roll back Rancher installed with Docker, refer to this page.

        Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.

        Rolling Back to v2.0.0-v2.1.5​

        If you are rolling back to versions in either of these scenarios, you must follow some extra instructions in order to get your clusters working.

        • Rolling back from v2.1.6+ to any version between v2.1.0 - v2.1.5 or v2.0.0 - v2.0.10.
        • Rolling back from v2.0.11+ to any version between v2.0.0 - v2.0.10.

        Because of the changes necessary to address CVE-2018-20321, special steps are necessary if the user wants to roll back to a previous version of Rancher where this vulnerability exists. The steps are as follows:

        1. Record the serviceAccountToken for each cluster. To do this, save the following script on a machine with kubectl access to the Rancher management plane and execute it. You will need to run these commands on the machine where the rancher container is running. Ensure JQ is installed before running the command. The commands will vary depending on how you installed Rancher.

          Rancher Installed with Docker

          docker exec <NAME OF RANCHER CONTAINER> kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json

          Rancher Installed on a Kubernetes Cluster

          kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json

        2. After executing the command a tokens.json file will be created. Important! Back up this file in a safe place. You will need it to restore functionality to your clusters after rolling back Rancher. If you lose this file, you may lose access to your clusters.**

        3. Rollback Rancher following the normal instructions.

        4. Once Rancher comes back up, every cluster managed by Rancher (except for Imported clusters) will be in an Unavailable state.

        5. Apply the backed up tokens based on how you installed Rancher.

          Rancher Installed with Docker

          Save the following script as apply_tokens.sh to the machine where the Rancher docker container is running. Also copy the tokens.json file created previously to the same directory as the script.

          set -e

          tokens=$(jq .[] -c tokens.json)
          for token in $tokens; do
              name=$(echo $token | jq -r .name)
              value=$(echo $token | jq -r .token)

              docker exec $1 kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
          done

          the script to allow execution (chmod +x apply_tokens.sh) and execute the script as follows:

          ./apply_tokens.sh <DOCKER CONTAINER NAME>

          After a few moments the clusters will go from Unavailable back to Available.

          Rancher Installed on a Kubernetes Cluster

          Save the following script as apply_tokens.sh to a machine with kubectl access to the Rancher management plane. Also copy the tokens.json file created previously to the same directory as the script.

          set -e

          tokens=$(jq .[] -c tokens.json)
          for token in $tokens; do
              name=$(echo $token | jq -r .name)
              value=$(echo $token | jq -r .token)

             kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
          done

          Set the script to allow execution (chmod +x apply_tokens.sh) and execute the script as follows:

          ./apply_tokens.sh

          After a few moments the clusters will go from Unavailable back to Available.

        6. Continue using Rancher as normal.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html index 303116de412..c3b52bc42ca 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting the Rancher Server Kubernetes Cluster | Rancher Manager - +
        Version: v2.0-v2.4

        Troubleshooting the Rancher Server Kubernetes Cluster

        This section describes how to troubleshoot an installation of Rancher on a Kubernetes cluster.

        Relevant Namespaces​

        Most of the troubleshooting will be done on objects in these 3 namespaces.

        • cattle-system - rancher deployment and pods.
        • ingress-nginx - Ingress controller pods and services.
        • cert-manager - cert-manager pods.

        "default backend - 404"​

        A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration.

        Things to check

        Check if Rancher is Running​

        Use kubectl to check the cattle-system system namespace and see if the Rancher pods are in a Running state.

        kubectl -n cattle-system get pods

        NAME                           READY     STATUS    RESTARTS   AGE
        pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

        If the state is not Running, run a describe on the pod and check the Events.

        kubectl -n cattle-system describe pod

        ...
        Events:
          Type     Reason                 Age   From                Message
          ----     ------                 ----  ----                -------
          Normal   Scheduled              11m   default-scheduler   Successfully assigned rancher-784d94f59b-vgqzh to localhost
          Normal   SuccessfulMountVolume  11m   kubelet, localhost  MountVolume.SetUp succeeded for volume "rancher-token-dj4mt"
          Normal   Pulling                11m   kubelet, localhost  pulling image "rancher/rancher:v2.0.4"
          Normal   Pulled                 11m   kubelet, localhost  Successfully pulled image "rancher/rancher:v2.0.4"
          Normal   Created                11m   kubelet, localhost  Created container
          Normal   Started                11m   kubelet, localhost  Started container

        Check the Rancher Logs​

        Use kubectl to list the pods.

        kubectl -n cattle-system get pods

        NAME                           READY     STATUS    RESTARTS   AGE
        pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

        Use kubectl and the pod name to list the logs from the pod.

        kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh

        Cert CN is "Kubernetes Ingress Controller Fake Certificate"​

        Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert.

        Note: if you are using LetsEncrypt to issue certs it can sometimes take a few minutes to issue the cert.

        Checking for issues with cert-manager issued certs (Rancher Generated or LetsEncrypt)​

        cert-manager has 3 parts.

        • cert-manager pod in the cert-manager namespace.
        • Issuer object in the cattle-system namespace.
        • Certificate object in the cattle-system namespace.

        Work backwards and do a kubectl describe on each object and check the events. You can track down what might be missing.

        For example there is a problem with the Issuer:

        kubectl -n cattle-system describe certificate
        ...
        Events:
          Type     Reason          Age                 From          Message
          ----     ------          ----                ----          -------
          Warning  IssuerNotReady  18s (x23 over 19m)  cert-manager  Issuer rancher not ready
        kubectl -n cattle-system describe issuer
        ...
        Events:
          Type     Reason         Age                 From          Message
          ----     ------         ----                ----          -------
          Warning  ErrInitIssuer  19m (x12 over 19m)  cert-manager  Error initializing issuer: secret "tls-rancher" not found
          Warning  ErrGetKeyPair  9m (x16 over 19m)   cert-manager  Error getting keypair for CA issuer: secret "tls-rancher" not found

        Checking for Issues with Your Own SSL Certs​

        Your certs get applied directly to the Ingress object in the cattle-system namespace.

        Check the status of the Ingress object and see if its ready.

        kubectl -n cattle-system describe ingress

        If its ready and the SSL is still not working you may have a malformed cert or secret.

        Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.

        kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller
        ...
        W0705 23:04:58.240571       7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found

        No matches for kind "Issuer"​

        The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown:

        Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1"

        Install cert-manager and try installing Rancher again.

        Canal Pods show READY 2/3​

        The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups.

        Once the network issue is resolved, the canal pods should timeout and restart to establish their connections.

        nginx-ingress-controller Pods show RESTARTS​

        The most common cause of this issue is the canal pods have failed to establish the overlay network. See canal Pods show READY 2/3 for troubleshooting.

        Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)​

        Some causes of this error include:

        • User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command docker ps:
        $ ssh user@server
        user@server$ docker ps
        CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES

        See Manage Docker as a non-root user how to set this up properly.

        • When using RedHat/CentOS as operating system, you cannot use the user root to connect to the nodes because of Bugzilla #1527565. You will need to add a separate user and configure it to access the Docker socket. See Manage Docker as a non-root user how to set this up properly.

        • SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using sshd -V on the host you are connecting to, or using netcat:

        $ nc xxx.xxx.xxx.xxx 22
        SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10

        Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: no key found​

        The key file specified as ssh_key_path cannot be accessed. Make sure that you specified the private key file (not the public key, .pub), and that the user that is running the rke command can access the private key file.

        Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain​

        The key file specified as ssh_key_path is not correct for accessing the node. Double-check if you specified the correct ssh_key_path for the node and if you specified the correct user to connect with.

        Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: cannot decode encrypted private keys​

        If you want to use encrypted private keys, you should use ssh-agent to load your keys with your passphrase. If the SSH_AUTH_SOCK environment variable is found in the environment where the rke command is run, it will be used automatically to connect to the node.

        Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?​

        The node is not reachable on the configured address and port.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.html b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.html index bbed9f2c6bf..03ff36f70a8 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.html @@ -5,14 +5,14 @@ Upgrading Rancher Installed on Kubernetes with Helm 2 | Rancher Manager - +
        Version: v2.0-v2.4

        Upgrading Rancher Installed on Kubernetes with Helm 2

        Helm 3 has been released. If you are using Helm 2, we recommend migrating to Helm 3 because it is simpler to use and more secure than Helm 2.

        The current instructions for Upgrading Rancher Installed on Kubernetes use Helm 3.

        This section provides a copy of the older instructions for upgrading Rancher with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

        The following instructions will guide you through using Helm to upgrade a Rancher server that is installed on a Kubernetes cluster.

        To upgrade the components in your Kubernetes cluster, or the definition of the Kubernetes services or add-ons, refer to the upgrade documentation for RKE, the Rancher Kubernetes Engine.

        If you installed Rancher using the RKE Add-on yaml, follow the directions to migrate or upgrade.

        Notes:

        Prerequisites

        • Review the known upgrade issues in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.
        • For air gap installs only, collect and populate images for the new Rancher server version. Follow the guide to populate your private registry with the images for the Rancher version that you want to upgrade to.

        Upgrade Outline

        Follow the steps to upgrade Rancher server:

        A. Back up Your Kubernetes Cluster that is Running Rancher Server​

        Take a one-time snapshot of your Kubernetes cluster running Rancher server. You'll use the snapshot as a restore point if something goes wrong during upgrade.

        B. Update the Helm chart repository​

        1. Update your local helm repo cache.

          helm repo update

        2. Get the repository name that you used to install Rancher.

          For information about the repos and their differences, see Helm Chart Repositories.

          • Latest: Recommended for trying out the newest features
            helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
          • Stable: Recommended for production environments
            helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
          • Alpha: Experimental preview of upcoming releases.
            helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
            Note: Upgrades are not supported to, from, or between Alphas.
          helm repo list

          NAME                   URL
          stable                 https://charts.helm.sh/stable
          rancher-<CHART_REPO>     https://releases.rancher.com/server-charts/<CHART_REPO>

          Note: If you want to switch to a different Helm chart repository, please follow the steps on how to switch repositories. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.

        1. Fetch the latest chart to install Rancher from the Helm chart repository.

          This command will pull down the latest charts and save it in the current directory as a .tgz file.

          helm fetch rancher-<CHART_REPO>/rancher

        C. Upgrade Rancher​

        This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.

        Get the values, which were passed with --set, from the current Rancher Helm chart that is installed.

        helm get values rancher

        hostname: rancher.my.org

        Note: There will be more values that are listed with this command. This is just an example of one of the values.

        If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher. Otherwise, follow Option A: Upgrading Rancher.

        Option A: Upgrading Rancher

        Upgrade Rancher to the latest version with all your settings.

        Take all the values from the previous step and append them to the command using --set key=value. Note: There will be many more options from the previous step that need to be appended.

        helm upgrade --install rancher rancher-<CHART_REPO>/rancher \
          --namespace cattle-system \
          --set hostname=rancher.my.org
        Option B: Reinstalling Rancher chart

        If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.

        1. Uninstall Rancher

          helm delete rancher

          In case this results in an error that the release "rancher" was not found, make sure you are using the correct deployment name. Use helm list to list the helm-deployed releases.

        2. Uninstall and reinstall cert-manager according to the instructions on the Upgrading Cert-Manager page.

        3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using --set key=value. Note: There will be many more options from the step 1 that need to be appended.

          helm install rancher-<CHART_REPO>/rancher \
          --name rancher \
          --namespace cattle-system \
          --set hostname=rancher.my.org

        D. Verify the Upgrade​

        Log into Rancher to confirm that the upgrade succeeded.

        Having network issues following upgrade?

        See Restoring Cluster Networking.

        Rolling Back​

        Should something go wrong, follow the roll back instructions to restore the snapshot you took before you preformed the upgrade.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.html b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.html index 8c8c7f9c778..b8dcc616292 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on.html @@ -5,13 +5,13 @@ Migrating from a Kubernetes Install with an RKE Add-on | Rancher Manager - +
        Version: v2.0-v2.4

        Migrating from a Kubernetes Install with an RKE Add-on

        Important: RKE add-on install is only supported up to Rancher v2.0.8

        If you are currently using the RKE add-on install method, please follow these directions to migrate to the Helm install.

        The following instructions will help guide you through migrating from the RKE Add-on install to managing Rancher with the Helm package manager.

        You will need the to have kubectl installed and the kubeconfig YAML file (kube_config_rancher-cluster.yml) generated by RKE.

        Note: This guide assumes a standard Rancher install. If you have modified any of the object names or namespaces, please adjust accordingly.

        Note: If you are upgrading from from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your cluster's certificates have expired, you will need to perform additional steps to rotate the certificates.

        Point kubectl at your Rancher Cluster​

        Make sure kubectl is using the correct kubeconfig YAML file. Set the KUBECONFIG environmental variable to point to kube_config_rancher-cluster.yml:

        export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml

        After setting the KUBECONFIG environment variable, verify that it contains the correct server parameter. It should point directly to one of your cluster nodes on port 6443.

        kubectl config view -o=jsonpath='{.clusters[*].cluster.server}'
        https://NODE:6443

        If the output from the command shows your Rancher hostname with the suffix /k8s/clusters, the wrong kubeconfig YAML file is configured. It should be the file that was created when you used RKE to create the cluster to run Rancher.

        Save your certificates​

        If you have terminated ssl on the Rancher cluster ingress, recover your certificate and key for use in the Helm install.

        Use kubectl to get the secret, decode the value and direct the output to a file.

        kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.crt }' | base64 -d > tls.crt
        kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.key }' | base64 -d > tls.key

        If you specified a private CA root cert

        kubectl -n cattle-system get secret cattle-keys-server -o jsonpath --template='{ .data.cacerts\.pem }' | base64 -d > cacerts.pem

        Remove previous Kubernetes objects​

        Remove the Kubernetes objects created by the RKE install.

        Note: Removing these Kubernetes components will not affect the Rancher configuration or database, but with any maintenance it is a good idea to create a backup of the data before hand. See Creating Backups-Kubernetes Install for details.

        kubectl -n cattle-system delete ingress cattle-ingress-http
        kubectl -n cattle-system delete service cattle-service
        kubectl -n cattle-system delete deployment cattle
        kubectl -n cattle-system delete clusterrolebinding cattle-crb
        kubectl -n cattle-system delete serviceaccount cattle-admin

        Remove addons section from rancher-cluster.yml​

        The addons section from rancher-cluster.yml contains all the resources needed to deploy Rancher using RKE. By switching to Helm, this part of the cluster configuration file is no longer needed. Open rancher-cluster.yml in your favorite text editor and remove the addons section:

        Important: Make sure you only remove the addons section from the cluster configuration file.

        nodes:
          - address: <IP> # hostname or IP to access nodes
            user: <USER> # root user (usually 'root')
            role: [controlplane,etcd,worker] # K8s roles for node
            ssh_key_path: <PEM_FILE> # path to PEM file
          - address: <IP>
            user: <USER>
            role: [controlplane,etcd,worker]
            ssh_key_path: <PEM_FILE>
          - address: <IP>
            user: <USER>
            role: [controlplane,etcd,worker]
            ssh_key_path: <PEM_FILE>

        services:
          etcd:
            snapshot: true
            creation: 6h
            retention: 24h

        # Remove addons section from here til end of file
        addons: |-
          ---
          ...
        # End of file

        Follow Helm and Rancher install steps​

        From here follow the standard install steps.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.html b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.html index 992818de48b..6e197d7d94e 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.html @@ -5,13 +5,13 @@ Upgrading to v2.0.7+ — Namespace Migration | Rancher Manager - +
        Version: v2.0-v2.4

        Upgrading to v2.0.7+ — Namespace Migration

        This section applies only to Rancher upgrades from v2.0.6 or earlier to v2.0.7 or later. Upgrades from v2.0.7 to later version are unaffected.

        In Rancher v2.0.6 and prior, system namespaces crucial for Rancher and Kubernetes operations were not assigned to any Rancher project by default. Instead, these namespaces existed independently from all Rancher projects, but you could move these namespaces into any project without affecting cluster operations.

        These namespaces include:

        • kube-system
        • kube-public
        • cattle-system
        • cattle-alerting1
        • cattle-logging1
        • cattle-pipeline1
        • ingress-nginx
        1 Only displays if this feature is enabled for the cluster.

        However, with the release of Rancher v2.0.7, the System project was introduced. This project, which is automatically created during the upgrade, is assigned the system namespaces above to hold these crucial components for safe keeping.

        During upgrades from Rancher v2.0.6- to Rancher v2.0.7+, all system namespaces are moved from their default location outside of all projects into the newly created System project. However, if you assigned any of your system namespaces to a project before upgrading, your cluster networking may encounter issues afterwards. This issue occurs because the system namespaces are not where the upgrade expects them to be during the upgrade, so it cannot move them to the System project.

        Note: If you are upgrading from from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your cluster's certificates have expired, you will need to perform additional steps to rotate the certificates.

        Preventing Cluster Networking Issues​

        You can prevent cluster networking issues from occurring during your upgrade to v2.0.7+ by unassigning system namespaces from all of your Rancher projects. Complete this task if you've assigned any of a cluster's system namespaces into a Rancher project.

        1. Log into the Rancher UI before upgrade.

        2. From the context menu, open the local cluster (or any of your other clusters).

        3. From the main menu, select Project/Namespaces.

        4. Find and select the following namespaces. Click Move and then choose None to move them out of your projects. Click Move again.

          Note: Some or all of these namespaces may already be unassigned from all projects.

          • kube-system
          • kube-public
          • cattle-system
          • cattle-alerting1
          • cattle-logging1
          • cattle-pipeline1
          • ingress-nginx
          1 Only displays if this feature is enabled for the cluster.
          Moving namespaces out of projects
          ![Moving Namespaces](/img/move-namespaces.png)

        5. Repeat these steps for each cluster where you've assigned system namespaces to projects.

        Result: All system namespaces are moved out of Rancher projects. You can now safely begin the upgrade.

        Restoring Cluster Networking​

        Reset the cluster nodes' network policies to restore connectivity.

        Prerequisites:

        Download and setup kubectl.

        1. From Terminal, change directories to your kubectl file that's generated during Rancher install, kube_config_rancher-cluster.yml. This file is usually in the directory where you ran RKE during Rancher installation.

        2. Before repairing networking, run the following two commands to make sure that your nodes have a status of Ready and that your cluster components are Healthy.

          kubectl --kubeconfig kube_config_rancher-cluster.yml get nodes

          NAME                          STATUS    ROLES                      AGE       VERSION
          165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.10.1
          165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.10.1
          165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.10.1

          kubectl --kubeconfig kube_config_rancher-cluster.yml get cs

          NAME                 STATUS    MESSAGE              ERROR
          scheduler            Healthy   ok
          controller-manager   Healthy   ok
          etcd-0               Healthy   {"health": "true"}
          etcd-2               Healthy   {"health": "true"}
          etcd-1               Healthy   {"health": "true"}

        3. Check the networkPolicy for all clusters by running the following command.

          kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o=custom-columns=ID:.metadata.name,NAME:.spec.displayName,NETWORKPOLICY:.spec.enableNetworkPolicy,APPLIEDNP:.status.appliedSpec.enableNetworkPolicy,ANNOTATION:.metadata.annotations."networking\.management\.cattle\.io/enable-network-policy"

          ID      NAME    NETWORKPOLICY   APPLIEDNP   ANNOTATION
          c-59ptz custom  <nil>           <nil>       <none>
          local   local   <nil>           <nil>       <none>

        1. Disable the networkPolicy for all clusters, still pointing toward your kube_config_rancher-cluster.yml.

          kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o jsonpath='{range .items[*]}{@.metadata.name}{"\n"}{end}' | xargs -I {} kubectl --kubeconfig kube_config_rancher-cluster.yml patch cluster {} --type merge -p '{"spec": {"enableNetworkPolicy": false},"status": {"appliedSpec": {"enableNetworkPolicy": false }}}'

          Tip: If you want to keep networkPolicy enabled for all created clusters, you can run the following command to disable networkPolicy for local cluster (i.e., your Rancher Server nodes):

           kubectl --kubeconfig kube_config_rancher-cluster.yml patch cluster local --type merge -p '{"spec": {"enableNetworkPolicy": false},"status": {"appliedSpec": {"enableNetworkPolicy": false }}}'

        2. Remove annotations for network policy for all clusters

          kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o jsonpath='{range .items[*]}{@.metadata.name}{"\n"}{end}' | xargs -I {} kubectl --kubeconfig kube_config_rancher-cluster.yml annotate cluster {} "networking.management.cattle.io/enable-network-policy"="false" --overwrite

          Tip: If you want to keep networkPolicy enabled for all created clusters, you can run the following command to disable networkPolicy for local cluster (i.e., your Rancher Server nodes):

           kubectl --kubeconfig kube_config_rancher-cluster.yml annotate cluster local "networking.management.cattle.io/enable-network-policy"="false" --overwrite

        3. Check the networkPolicy for all clusters again to make sure the policies have a status of false .

          kubectl --kubeconfig kube_config_rancher-cluster.yml get cluster -o=custom-columns=ID:.metadata.name,NAME:.spec.displayName,NETWORKPOLICY:.spec.enableNetworkPolicy,APPLIEDNP:.status.appliedSpec.enableNetworkPolicy,ANNOTATION:.metadata.annotations."networking\.management\.cattle\.io/enable-network-policy"

          ID      NAME    NETWORKPOLICY   APPLIEDNP   ANNOTATION
          c-59ptz custom  false           false       false
          local   local   false           false       false

        4. Remove all network policies from all namespaces. Run this command for each cluster, using the kubeconfig generated by RKE.

          for namespace in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get ns -o custom-columns=NAME:.metadata.name --no-headers); do
              kubectl --kubeconfig kube_config_rancher-cluster.yml -n $namespace delete networkpolicy --all;
          done

        5. Remove all the projectnetworkpolicies created for the clusters, to make sure networkpolicies are not recreated.

          for cluster in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get clusters -o custom-columns=NAME:.metadata.name --no-headers); do
              for project in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get project -n $cluster -o custom-columns=NAME:.metadata.name --no-headers); do
                  kubectl --kubeconfig kube_config_rancher-cluster.yml delete projectnetworkpolicy -n $project --all
              done
          done

          Tip: If you want to keep networkPolicy enabled for all created clusters, you can run the following command to disable networkPolicy for local cluster (i.e., your Rancher Server nodes):

           for project in $(kubectl --kubeconfig kube_config_rancher-cluster.yml get project -n local -o custom-columns=NAME:.metadata.name --no-headers); do
               kubectl --kubeconfig kube_config_rancher-cluster.yml -n $project delete projectnetworkpolicy --all;
           done

        6. Wait a few minutes and then log into the Rancher UI.

          • If you can access Rancher, you're done, so you can skip the rest of the steps.
          • If you still can't access Rancher, complete the steps below.

        7. Force your pods to recreate themselves by entering the following command.

          kubectl --kubeconfig kube_config_rancher-cluster.yml delete pods -n cattle-system --all

        8. Log into the Rancher UI and view your clusters. Created clusters will show errors from attempting to contact Rancher while it was unavailable. However, these errors should resolve automatically.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/install-docker.html b/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/install-docker.html index 5193ff3b15d..76364b5a8c8 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/install-docker.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/install-docker.html @@ -5,13 +5,13 @@ Installing Docker | Rancher Manager - +
        Version: v2.0-v2.4

        Installing Docker

        Docker is required to be installed on nodes where the Rancher server will be installed with Helm or Docker.

        There are a couple of options for installing Docker. One option is to refer to the official Docker documentation about how to install Docker on Linux. The steps will vary based on the Linux distribution.

        Another option is to use one of Rancher's Docker installation scripts, which are available for most recent versions of Docker.

        For example, this command could be used to install Docker 19.03 on Ubuntu:

        curl https://releases.rancher.com/install-docker/19.03.sh | sh

        Rancher has installation scripts for every version of upstream Docker that Kubernetes supports. To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher's Docker installation scripts.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html b/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html index 2954c4787f6..6514fa88a56 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html @@ -5,7 +5,7 @@ Port Requirements | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        Port Requirements

        To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.

        Rancher Nodes

        The following table lists the ports that need to be open to and from nodes that are running the Rancher server.

        The port requirements differ based on the Rancher server architecture.

        Notes:

        • Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example).
        • Kubernetes recommends TCP 30000-32767 for node port services.
        • For firewalls, traffic may need to be enabled within the cluster and pod CIDR.

        Ports for Rancher Server Nodes on K3s​

        Click to expand

        The K3s server needs port 6443 to be accessible by the nodes.

        The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.

        If you wish to utilize the metrics server, you will need to open port 10250 on each node.

        Important: The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.

        The following tables break down the port requirements for inbound and outbound traffic:

        Inbound Rules for Rancher Server Nodes
        ProtocolPortSourceDescription
        TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
        TCP443
        • server nodes
        • agent nodes
        • hosted/imported Kubernetes
        • any source that needs to be able to use the Rancher UI or API
        		Rancher agent, Rancher UI/API, kubectl
        TCP6443K3s server nodesKubernetes API
        UDP8472K3s server and agent nodesRequired only for Flannel VXLAN.
        TCP10250K3s server and agent nodeskubelet
        Outbound Rules for Rancher Nodes
        ProtocolPortDestinationDescription
        TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
        TCP443git.rancher.ioRancher catalog
        TCP2376Any node IP from a node created using Node driverDocker daemon TLS port used by Docker Machine
        TCP6443Hosted/Imported Kubernetes APIKubernetes API server

        Ports for Rancher Server Nodes on RKE​

        Click to expand

        Typically Rancher is installed on three RKE nodes that all have the etcd, control plane and worker roles.

        The following tables break down the port requirements for traffic between the Rancher nodes:

        Rules for traffic between Rancher nodes
        ProtocolPortDescription
        TCP443Rancher agents
        TCP2379etcd client requests
        TCP2380etcd peer communication
        TCP6443Kubernetes apiserver
        UDP8472Canal/Flannel VXLAN overlay networking
        TCP9099Canal/Flannel livenessProbe/readinessProbe
        TCP10250kubelet
        TCP10254Ingress controller livenessProbe/readinessProbe

        The following tables break down the port requirements for inbound and outbound traffic:

        Inbound Rules for Rancher Nodes
        ProtocolPortSourceDescription
        TCP22RKE CLISSH provisioning of node by RKE
        TCP80Load Balancer/Reverse ProxyHTTP traffic to Rancher UI/API
        TCP443
        • Load Balancer/Reverse Proxy
        • IPs of all cluster nodes and other API/UI clients
        		HTTPS traffic to Rancher UI/API
        TCP6443Kubernetes API clientsHTTPS traffic to Kubernetes API
        Outbound Rules for Rancher Nodes
        ProtocolPortDestinationDescription
        TCP44335.160.43.145,35.167.242.46,52.33.59.17Rancher catalog (git.rancher.io)
        TCP22Any node created using a node driverSSH provisioning of node by node driver
        TCP2376Any node created using a node driverDocker daemon TLS port used by node driver
        TCP6443Hosted/Imported Kubernetes APIKubernetes API server
        TCPProvider dependentPort of the Kubernetes API endpoint in hosted clusterKubernetes API

        Ports for Rancher Server in Docker​

        Click to expand

        The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic:

        Inbound Rules for Rancher Node
        ProtocolPortSourceDescription
        TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
        TCP443
        • hosted/imported Kubernetes
        • any source that needs to be able to use the Rancher UI or API
        		Rancher agent, Rancher UI/API, kubectl
        Outbound Rules for Rancher Node
        ProtocolPortSourceDescription
        TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
        TCP443git.rancher.ioRancher catalog
        TCP2376Any node IP from a node created using a node driverDocker daemon TLS port used by Docker Machine
        TCP6443Hosted/Imported Kubernetes APIKubernetes API server

        Downstream Kubernetes Cluster Nodes

        Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.

        The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different cluster types.

        The following diagram depicts the ports that are opened for each cluster type.

        Port Requirements for the Rancher Management Plane

        Basic Port Requirements

        Tip:

        If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in Commonly Used Ports as your port reference instead of the comprehensive tables below.

        Ports for Rancher Launched Kubernetes Clusters using Node Pools​

        Click to expand

        The following table depicts the port requirements for Rancher Launched Kubernetes with nodes created in an Infrastructure Provider.

        Note: The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.

        From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
        Rancher Nodes (1)22 TCPgit.rancher.io
        2376 TCP
        etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
        2380 TCP
        6443 TCP
        8472 UDP
        9099 TCP (4)
        Control Plane Nodes443 TCP (3)2379 TCP443 TCP
        2380 TCP
        6443 TCP
        8472 UDP
        10250 TCP
        9099 TCP (4)
        10254 TCP (4)
        Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
        8472 UDP
        9099 TCP (4)
        10254 TCP (4)
        Kubernetes API Clients6443 TCP (5)
        Workload Clients or Load Balancer30000-32767 TCP / UDP
        (nodeport)
        80 TCP (Ingress)
        443 TCP (Ingress)
        Notes:

        1. Nodes running standalone server or Rancher HA deployment.
        2. Required to fetch Rancher chart library.
        3. Only without external load balancer in front of Rancher.
        4. Local traffic to the node itself (not across nodes).
        5. Only if Authorized Cluster Endpoints are activated.

        Ports for Rancher Launched Kubernetes Clusters using Custom Nodes​

        Click to expand

        The following table depicts the port requirements for Rancher Launched Kubernetes with Custom Nodes.

        From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
        Rancher Nodes (1)git.rancher.io
        etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
        2380 TCP
        6443 TCP
        8472 UDP
        4789 UDP (6)
        9099 TCP (4)
        Control Plane Nodes443 TCP (3)2379 TCP443 TCP
        2380 TCP
        6443 TCP
        8472 UDP
        4789 UDP (6)
        10250 TCP
        9099 TCP (4)
        10254 TCP (4)
        Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
        8472 UDP
        4789 UDP (6)
        9099 TCP (4)
        10254 TCP (4)
        Kubernetes API Clients6443 TCP (5)
        Workload Clients or Load Balancer30000-32767 TCP / UDP
        (nodeport)
        80 TCP (Ingress)
        443 TCP (Ingress)
        Notes:

        1. Nodes running standalone server or Rancher HA deployment.
        2. Required to fetch Rancher chart library.
        3. Only without external load balancer in front of Rancher.
        4. Local traffic to the node itself (not across nodes).
        5. Only if Authorized Cluster Endpoints are activated.
        6. Only if using Overlay mode on Windows cluster.

        Ports for Hosted Kubernetes Clusters​

        Click to expand

        The following table depicts the port requirements for hosted clusters.

        From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
        Rancher Nodes (1)Kubernetes API
        Endpoint Port (2)        		git.rancher.io
        8443 TCP
        9443 TCP
        Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
        Kubernetes API ClientsCluster / Provider Specific (6)
        Workload ClientCluster / Provider Specific (7)
        Notes:

        1. Nodes running standalone server or Rancher HA deployment.
        2. Only for hosted clusters.
        3. Required to fetch Rancher chart library.
        4. Only without external load balancer.
        5. From worker nodes.
        6. For direct access to the Kubernetes API without Rancher.
        7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

        Ports for Imported Clusters​

        Click to expand

        The following table depicts the port requirements for imported clusters.

        From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
        Rancher Nodes (1)Kubernetes API
        Endpoint Port (2)        		git.rancher.io
        8443 TCP
        9443 TCP
        Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
        Kubernetes API ClientsCluster / Provider Specific (6)
        Workload ClientCluster / Provider Specific (7)
        Notes:

        1. Nodes running standalone server or Rancher HA deployment.
        2. Only for hosted clusters.
        3. Required to fetch Rancher chart library.
        4. Only without external load balancer.
        5. From worker nodes.
        6. For direct access to the Kubernetes API without Rancher.
        7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

        Other Port Considerations

        Commonly Used Ports​

        These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.

        ProtocolPortDescription
        TCP22Node driver SSH provisioning
        TCP179Calico BGP Port
        TCP2376Node driver Docker daemon TLS port
        TCP2379etcd client requests
        TCP2380etcd peer communication
        UDP8472Canal/Flannel VXLAN overlay networking
        UDP4789Flannel VXLAN overlay networking on Windows cluster
        TCP8443Rancher webhook
        TCP9099Canal/Flannel livenessProbe/readinessProbe
        TCP9100Default port required by Monitoring to scrape metrics from Linux node-exporters
        TCP9443Rancher webhook
        TCP9796Default port required by Monitoring to scrape metrics from Windows node-exporters
        TCP6783Weave Port
        UDP6783-6784Weave UDP Ports
        TCP10250kubelet API
        TCP10254Ingress controller livenessProbe/readinessProbe
        TCP/UDP30000-32767NodePort port range

        Local Node Traffic​

        Ports marked as local traffic (i.e., 9099 TCP) in the above requirements are used for Kubernetes healthchecks (livenessProbe andreadinessProbe). These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.

        However, this traffic may be blocked when:

        • You have applied strict host firewall policies on the node.
        • You are using nodes that have multiple interfaces (multihomed).

        In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances.

        Rancher AWS EC2 Security Group​

        When using the AWS EC2 node driver to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called rancher-nodes. The following rules are automatically added to this security group.

        TypeProtocolPort RangeSource/DestinationRule Type
        SSHTCP220.0.0.0/0Inbound
        HTTPTCP800.0.0.0/0Inbound
        Custom TCP RuleTCP4430.0.0.0/0Inbound
        Custom TCP RuleTCP23760.0.0.0/0Inbound
        Custom TCP RuleTCP2379-2380sg-xxx (rancher-nodes)Inbound
        Custom UDP RuleUDP4789sg-xxx (rancher-nodes)Inbound
        Custom TCP RuleTCP64430.0.0.0/0Inbound
        Custom UDP RuleUDP8472sg-xxx (rancher-nodes)Inbound
        Custom TCP RuleTCP10250-10252sg-xxx (rancher-nodes)Inbound
        Custom TCP RuleTCP10256sg-xxx (rancher-nodes)Inbound
        Custom TCP RuleTCP30000-327670.0.0.0/0Inbound
        Custom UDP RuleUDP30000-327670.0.0.0/0Inbound
        All trafficAllAll0.0.0.0/0Outbound

        Opening SUSE Linux Ports​

        SUSE Linux may have a firewall that blocks all ports by default. To open the ports needed for adding the host to a custom cluster,

        1. SSH into the instance.
        2. Edit /etc/sysconfig/SuSEfirewall2 and open the required ports. In this example, ports 9796 and 10250 are also opened for monitoring:
          FW_SERVICES_EXT_TCP="22 80 443 2376 2379 2380 6443 9099 9796 10250 10254 30000:32767"
          FW_SERVICES_EXT_UDP="8472 30000:32767"
          FW_ROUTE=yes
        3. Restart the firewall with the new ports:
          SuSEfirewall2

        Result: The node has the open ports required to be added to a custom cluster.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html index 63a5be7c4f4..469deffcb7f 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html @@ -5,7 +5,7 @@ 1. Set up Infrastructure and Private Registry | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        1. Set up Infrastructure and Private Registry

        In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private Docker registry that must be available to your Rancher node(s).

        An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.

        The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to this page.

        We recommend setting up the following infrastructure for a high-availability installation:

        • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
        • An external database to store the cluster data. PostgreSQL, MySQL, and etcd are supported.
        • A load balancer to direct traffic to the two nodes.
        • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
        • A private Docker registry to distribute Docker images to your machines.

        1. Set up Linux Nodes​

        These hosts will be disconnected from the internet, but require being able to connect with your private registry.

        Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

        For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

        2. Set up External Datastore​

        The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

        For a high-availability K3s installation, you will need to set up one of the following external databases:

        • PostgreSQL (certified against versions 10.7 and 11.5)
        • MySQL (certified against version 5.7)
        • etcd (certified against version 3.3.15)

        When you install Kubernetes, you will pass in details for K3s to connect to the database.

        For an example of one way to set up the database, refer to this tutorial for setting up a MySQL database on Amazon's RDS service.

        For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

        3. Set up the Load Balancer​

        You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

        When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

        When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

        For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

        • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
        • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

        For an example showing how to set up an NGINX load balancer, refer to this page.

        For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

        Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

        4. Set up the DNS Record​

        Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

        Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

        You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

        For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

        5. Set up a Private Docker Registry​

        Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.

        In a later step, when you set up your K3s Kubernetes cluster, you will create a private registries configuration file with details from this registry.

        If you need help with creating a private registry, please refer to the official Docker documentation.

        Next: Collect and Publish Images to your Private Registry​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html index 43509f06692..4804540786e 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html @@ -5,7 +5,7 @@ 3. Install Kubernetes (Skip for Docker Installs) | Rancher Manager - + @@ -15,7 +15,7 @@ Also obtain the K3s install script at 
        INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

        Install K3s on each agent:

        INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

        Note, take care to ensure you replace myserver with the IP or valid DNS of the server and replace mynodetoken with the node-token from the server. The node-token is on the server at /var/lib/rancher/k3s/server/node-token

        Note: K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.

        4. Save and Start Using the kubeconfig File​

        When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

        To use this kubeconfig file,

        1. Install kubectl, a Kubernetes command-line tool.
        2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
        3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
        apiVersion: v1
        clusters:
        - cluster:
            certificate-authority-data: [CERTIFICATE-DATA]
            server: [LOAD-BALANCER-DNS]:6443 # Edit this line
          name: default
        contexts:
        - context:
            cluster: default
            user: default
          name: default
        current-context: default
        kind: Config
        preferences: {}
        users:
        - name: default
          user:
            password: [PASSWORD]
            username: admin

        Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

        kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

        For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

        Note on Upgrading​

        Upgrading an air-gap environment can be accomplished in the following manner:

        1. Download the new air-gap images (tar file) from the releases page for the version of K3s you will be upgrading to. Place the tar in the /var/lib/rancher/k3s/agent/images/ directory on each node. Delete the old tar file.
        2. Copy and replace the old K3s binary in /usr/local/bin on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
        3. Restart the K3s service (if not restarted automatically by installer).

        Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

        Issues or errors?​

        See the Troubleshooting page.

        Next: Install Rancher​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html index 194a7cfc563..c53441fdcd9 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html @@ -5,7 +5,7 @@ 4. Install Rancher | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        4. Install Rancher

        This section is about how to deploy Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are tabs for either a high availability (recommended) or a Docker installation.

        Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

        This section describes installing Rancher in five parts:

        1. Add the Helm Chart Repository

        From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.

        1. If you haven't already, install helm locally on a workstation that has internet access. Note: Refer to the Helm version requirements to choose a version of Helm to install Rancher.

        2. Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

          • Latest: Recommended for trying out the newest features
            helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
          • Stable: Recommended for production environments
            helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
          • Alpha: Experimental preview of upcoming releases.
            helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
            Note: Upgrades are not supported to, from, or between Alphas.

        3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a .tgz file.

          helm fetch rancher-<CHART_REPO>/rancher

          If you require a specific version of Rancher, you can fetch this with the Helm --version parameter like in the following example:

          helm fetch rancher-stable/rancher --version=v2.4.8

        2. Choose your SSL Configuration

        Rancher Server is designed to be secure by default and requires SSL/TLS configuration.

        When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.

        Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

        ConfigurationChart optionDescriptionRequires cert-manager
        Rancher Generated Self-Signed Certificatesingress.tls.source=rancherUse certificates issued by Rancher's generated CA (self signed)
        This is the default and does not need to be added when rendering the Helm template.        		yes
        Certificates from Filesingress.tls.source=secretUse your own certificate files by creating Kubernetes Secret(s).
        This option must be passed when rendering the Rancher Helm template.        		no

        3. Render the Rancher Helm Template

        When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.

        Chart OptionChart ValueDescription
        certmanager.version<version>Configure proper Rancher TLS issuer depending of running cert-manager version.
        systemDefaultRegistry<REGISTRY.YOURDOMAIN.COM:PORT>Configure Rancher server to always pull from your private registry when provisioning clusters.
        useBundledSystemCharttrueConfigure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. Available as of v2.3.0

        Based on the choice your made in B. Choose your SSL Configuration, complete one of the procedures below.

        Option A: Default Self-Signed Certificate​

        Click to expand

        By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.

        Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade cert-manager documentation.

        1. From a system connected to the internet, add the cert-manager repo to Helm.

          helm repo add jetstack https://charts.jetstack.io
          helm repo update

        2. Fetch the latest cert-manager chart available from the Helm chart repository.

          helm fetch jetstack/cert-manager --version v1.0.4

        3. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

          helm template cert-manager ./cert-manager-v1.0.4.tgz --output-dir . \
              --namespace cert-manager \
              --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
              --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
              --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

        4. Download the required CRD file for cert-manager

          curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml

        5. Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

        Placeholder | Description
        ------------|-------------
        `<VERSION>` | The version number of the output tarball.
        `<RANCHER.YOURDOMAIN.COM>` | The DNS name you pointed at your load balancer.
        `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.
        `<CERTMANAGER_VERSION>` | Cert-manager version running on k8s cluster.

         ```plain
        helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
         --namespace cattle-system \
         --set hostname=<RANCHER.YOURDOMAIN.COM> \
         --set certmanager.version=<CERTMANAGER_VERSION> \
         --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
         --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
         --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

        **Optional**: To install a specific Rancher version, set the `rancherImageTag` value, example: `--set rancherImageTag=v2.3.6`

        </details>

        ### Option B: Certificates From Files using Kubernetes Secrets

        <details id="k8s-2">
          <summary>Click to expand</summary>

        Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the `hostname` option in the command below, or the ingress controller will fail to provision the site for Rancher.

        Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

        | Placeholder                      | Description                                     |
        | -------------------------------- | ----------------------------------------------- |
        | `<VERSION>`                      | The version number of the output tarball.       |
        | `<RANCHER.YOURDOMAIN.COM>`       | The DNS name you pointed at your load balancer. |
        | `<REGISTRY.YOURDOMAIN.COM:PORT>` | The DNS name for your private registry.         |

        ```plain
           helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
            --namespace cattle-system \
            --set hostname=<RANCHER.YOURDOMAIN.COM> \
            --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
            --set ingress.tls.source=secret \
            --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
            --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

        If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

           helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
            --namespace cattle-system \
            --set hostname=<RANCHER.YOURDOMAIN.COM> \
            --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
            --set ingress.tls.source=secret \
            --set privateCA=true \
            --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
            --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts

        Optional: To install a specific Rancher version, set the rancherImageTag value, example: --set rancherImageTag=v2.3.6

        Then refer to Adding TLS Secrets to publish the certificate files so Rancher and the ingress controller can use them.

        4. Install Rancher

        Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.

        Use kubectl to create namespaces and apply the rendered manifests.

        If you choose to use self-signed certificates in B. Choose your SSL Configuration, install cert-manager.

        For Self-Signed Certificate Installs, Install Cert-manager​

        Click to expand

        If you are using self-signed certificates, install cert-manager:

        1. Create the namespace for cert-manager.
        kubectl create namespace cert-manager
        1. Create the cert-manager CustomResourceDefinitions (CRDs).
        kubectl apply -f cert-manager/cert-manager-crd.yaml
        > **Note:**
        > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
        1. Launch cert-manager.
        kubectl apply -R -f ./cert-manager

        Install Rancher with kubectl​

        kubectl create namespace cattle-system
        kubectl -n cattle-system apply -R -f ./rancher

        Step Result: If you are installing Rancher v2.3.0+, the installation is complete.

        Note: If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

        5. For Rancher versions before v2.3.0, Configure System Charts

        If you are installing Rancher versions before v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in Github, an air gapped installation will not be able to access these charts. Therefore, you must configure the Rancher system charts.

        Additional Resources

        These resources could be helpful when installing Rancher:

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html index 86597e5ca2c..5b1b9c8b3fa 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html @@ -5,13 +5,13 @@ 2. Collect and Publish Images to your Private Registry | Rancher Manager - +
        Version: v2.0-v2.4

        2. Collect and Publish Images to your Private Registry

        This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.

        By default, all images used to provision Kubernetes clusters or launch any tools in Rancher, e.g. monitoring, pipelines, alerts, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.

        Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.

        The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any downstream Kubernetes clusters using Windows nodes, there are separate instructions to support the images needed.

        Prerequisites:

        You must have a private registry available to use.

        If the registry has certs, follow this K3s documentation about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.

        For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.

        1. Find the required assets for your Rancher version
        2. Collect the cert-manager image (unless you are bringing your own certificates or terminating TLS on a load balancer)
        3. Save the images to your workstation
        4. Populate the private registry

        Prerequisites​

        These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.

        If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.

        1. Find the required assets for your Rancher version​

        1. Go to our releases page, find the Rancher v2.x.x release that you want to install, and click Assets. Note: Don't use releases marked rc or Pre-release, as they are not stable for production environments.

        2. From the release's Assets section, download the following files, which are required to install Rancher in an air gap environment:

        Release FileDescription
        rancher-images.txtThis file contains a list of images needed to install Rancher, provision clusters and user Rancher tools.
        rancher-save-images.shThis script pulls all the images in the rancher-images.txt from Docker Hub and saves all of the images as rancher-images.tar.gz.
        rancher-load-images.shThis script loads images from the rancher-images.tar.gz file and pushes them to your private registry.

        2. Collect the cert-manager image​

        Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.

        In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the cert-manager image to rancher-images.txt as well.

        1. Fetch the latest cert-manager Helm chart and parse the template for image details:

          Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

          helm repo add jetstack https://charts.jetstack.io
          helm repo update
          helm fetch jetstack/cert-manager --version v1.0.4
          helm template ./cert-manager-<version>.tgz | grep -oP '(?<=image: ").*(?=")' >> ./rancher-images.txt

        2. Sort and unique the images list to remove any overlap between the sources:

          sort -u rancher-images.txt -o rancher-images.txt

        3. Save the images to your workstation​

        1. Make rancher-save-images.sh an executable:

          chmod +x rancher-save-images.sh

        2. Run rancher-save-images.sh with the rancher-images.txt image list to create a tarball of all the required images:

          ./rancher-save-images.sh --image-list ./rancher-images.txt

          Result: Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named rancher-images.tar.gz. Check that the output is in the directory.

        4. Populate the private registry​

        Next, you will move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

        Move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

        The rancher-images.txt is expected to be on the workstation in the same directory that you are running the rancher-load-images.sh script. The rancher-images.tar.gz should also be in the same directory.

        1. Log into your private registry if required:

          docker login <REGISTRY.YOURDOMAIN.COM:PORT>

        2. Make rancher-load-images.sh an executable:

          chmod +x rancher-load-images.sh

        3. Use rancher-load-images.sh to extract, tag and push rancher-images.txt and rancher-images.tar.gz to your private registry:

          ./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>

        Next step for Kubernetes Installs - Launch a Kubernetes Cluster​

        Next step for Docker Installs - Install Rancher​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html index 6baf8bc3cd2..1c865a64c30 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html @@ -5,14 +5,14 @@ 2. Install Kubernetes | Rancher Manager - +
        Version: v2.0-v2.4

        2. Install Kubernetes

        Once the infrastructure is ready, you can continue with setting up an RKE cluster to install Rancher in.

        Installing Docker​

        First, you have to install Docker and setup the HTTP proxy on all three Linux nodes. For this perform the following steps on all three nodes.

        For convenience export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell:

        export proxy_host="10.0.0.5:8888"
        export HTTP_PROXY=http://${proxy_host}
        export HTTPS_PROXY=http://${proxy_host}
        export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16

        Next configure apt to use this proxy when installing packages. If you are not using Ubuntu, you have to adapt this step accordingly:

        cat <<'EOF' | sudo tee /etc/apt/apt.conf.d/proxy.conf > /dev/null
        Acquire::http::Proxy "http://${proxy_host}/";
        Acquire::https::Proxy "http://${proxy_host}/";
        EOF

        Now you can install Docker:

        curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh

        Then ensure that your current user is able to access the Docker daemon without sudo:

        sudo usermod -aG docker YOUR_USERNAME

        And configure the Docker daemon to use the proxy to pull images:

        sudo mkdir -p /etc/systemd/system/docker.service.d
        cat <<'EOF' | sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null
        [Service]
        Environment="HTTP_PROXY=http://${proxy_host}"
        Environment="HTTPS_PROXY=http://${proxy_host}"
        Environment="NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"
        EOF

        To apply the configuration, restart the Docker daemon:

        sudo systemctl daemon-reload
        sudo systemctl restart docker

        Creating the RKE Cluster​

        You need several command line tools on the host where you have SSH access to the Linux nodes to create and interact with the cluster:

        sudo curl -fsSL -o /usr/local/bin/rke https://github.com/rancher/rke/releases/download/v1.1.4/rke_linux-amd64
        sudo chmod +x /usr/local/bin/rke
        curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
        chmod +x ./kubectl
        sudo mv ./kubectl /usr/local/bin/kubectl
        curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
        chmod +x get_helm.sh
        sudo ./get_helm.sh

        Next, create a YAML file that describes the RKE cluster. Ensure that the IP addresses of the nodes and the SSH username are correct. For more information on the cluster YAML, have a look at the RKE documentation.

        nodes:
          - address: 10.0.1.200
            user: ubuntu
            role: [controlplane,worker,etcd]
          - address: 10.0.1.201
            user: ubuntu
            role: [controlplane,worker,etcd]
          - address: 10.0.1.202
            user: ubuntu
            role: [controlplane,worker,etcd]

        services:
          etcd:
            backup_config:
              interval_hours: 12
              retention: 6

        After that, you can create the Kubernetes cluster by running:

        rke up --config rancher-cluster.yaml

        RKE creates a state file called rancher-cluster.rkestate, this is needed if you want to perform updates, modify your cluster configuration or restore it from a backup. It also creates a kube_config_rancher-cluster.yaml file, that you can use to connect to the remote Kubernetes cluster locally with tools like kubectl or Helm. Make sure to save all of these files in a secure location, for example by putting them into a version control system.

        To have a look at your cluster run:

        export KUBECONFIG=kube_config_rancher-cluster.yaml
        kubectl cluster-info
        kubectl get pods --all-namespaces

        You can also verify that your external load balancer works, and the DNS entry is set up correctly. If you send a request to either, you should receive HTTP 404 response from the ingress controller:

        $ curl 10.0.1.100
        default backend - 404
        $ curl rancher.example.com
        default backend - 404

        Save Your Files​

        Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

        Save a copy of the following files in a secure location:

        • rancher-cluster.yml: The RKE cluster configuration file.
        • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
        • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains the current state of the cluster including the RKE configuration and the certificates.

        Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

        Issues or errors?​

        See the Troubleshooting page.

        Next: Install Rancher​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html index 8be1e96ab3d..4b2d1ed15fa 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html @@ -5,13 +5,13 @@ 3. Install Rancher | Rancher Manager - +
        Version: v2.0-v2.4

        3. Install Rancher

        Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through cert-manager. In a real-world use-case you will likely use Let's Encrypt or provide your own certificate.

        Note: These installation instructions assume you are using Helm 3.

        Install cert-manager​

        Add the cert-manager helm repository:

        helm repo add jetstack https://charts.jetstack.io

        Create a namespace for cert-manager:

        kubectl create namespace cert-manager

        Install the CustomResourceDefinitions of cert-manager:

        kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.2/cert-manager.crds.yaml

        And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:

        helm upgrade --install cert-manager jetstack/cert-manager \
          --namespace cert-manager --version v0.15.2 \
          --set http_proxy=http://${proxy_host} \
          --set https_proxy=http://${proxy_host} \
          --set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local

        Now you should wait until cert-manager is finished starting up:

        kubectl rollout status deployment -n cert-manager cert-manager
        kubectl rollout status deployment -n cert-manager cert-manager-webhook

        Install Rancher​

        Next you can install Rancher itself. First add the helm repository:

        helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

        Create a namespace:

        kubectl create namespace cattle-system

        And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata:

        helm upgrade --install rancher rancher-latest/rancher \
           --namespace cattle-system \
           --set hostname=rancher.example.com \
           --set proxy=http://${proxy_host}

        After waiting for the deployment to finish:

        kubectl rollout status deployment -n cattle-system rancher

        You can now navigate to https://rancher.example.com and start using Rancher.

        Note: If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

        Additional Resources​

        These resources could be helpful when installing Rancher:

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html index 0e0638a6445..8118a94ef4b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html @@ -5,14 +5,14 @@ 1. Set up Infrastructure | Rancher Manager - +
        Version: v2.0-v2.4

        1. Set up Infrastructure

        In this section, you will provision the underlying infrastructure for your Rancher management server with internete access through a HTTP proxy.

        To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

        • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
        • A load balancer to direct front-end traffic to the three nodes.
        • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

        These nodes must be in the same region/data center. You may place these servers in separate availability zones.

        Why three nodes?​

        In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

        The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

        1. Set up Linux Nodes​

        These hosts will connect to the internet through an HTTP proxy.

        Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

        For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

        2. Set up the Load Balancer​

        You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

        When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

        When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

        For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

        • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
        • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

        For an example showing how to set up an NGINX load balancer, refer to this page.

        For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

        Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

        3. Set up the DNS Record​

        Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

        Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

        You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

        For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

        Next: Set up a Kubernetes cluster​

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html index 02515751612..2c3e5ad09bb 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html @@ -5,14 +5,14 @@ Certificate Troubleshooting | Rancher Manager - +
        Version: v2.0-v2.4

        Certificate Troubleshooting

        How Do I Know if My Certificates are in PEM Format?​

        You can recognize the PEM format by the following traits:

        • The file begins with the following header:
          -----BEGIN CERTIFICATE-----
        • The header is followed by a long string of characters.
        • The file ends with a footer: -----END CERTIFICATE-----

        PEM Certificate Example:

        ----BEGIN CERTIFICATE-----
        MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
        ... more lines
        VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
        -----END CERTIFICATE-----

        PEM Certificate Key Example:

        -----BEGIN RSA PRIVATE KEY-----
        MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
        ... more lines
        VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
        -----END RSA PRIVATE KEY-----

        If your key looks like the example below, see Converting a Certificate Key From PKCS8 to PKCS1.

        -----BEGIN PRIVATE KEY-----
        MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
        ... more lines
        VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
        -----END PRIVATE KEY-----

        Converting a Certificate Key From PKCS8 to PKCS1​

        If you are using a PKCS8 certificate key file, Rancher will log the following line:

        ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})

        To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:

        openssl rsa -in key.pem -out convertedkey.pem

        You can now use convertedkey.pem as certificate key file for Rancher.

        What is the Order of Certificates if I Want to Add My Intermediate(s)?​

        The order of adding certificates is as follows:

        -----BEGIN CERTIFICATE-----
        %YOUR_CERTIFICATE%
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        %YOUR_INTERMEDIATE_CERTIFICATE%
        -----END CERTIFICATE-----

        How Do I Validate My Certificate Chain?​

        You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. The ca.pem file must be the same as you added to the rancher/rancher container.

        When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

        Command:

        openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
        ...
            Verify return code: 0 (ok)
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html index f9083ca8328..90b62635eac 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html @@ -5,13 +5,13 @@ Rolling Back Rancher Installed with Docker | Rancher Manager - +
        Version: v2.0-v2.4

        Rolling Back Rancher Installed with Docker

        If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before Docker Upgrade. Rolling back restores:

        • Your previous version of Rancher.
        • Your data backup created before upgrade.

        Before You Start​

        During rollback to a prior version of Rancher, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

        docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

        In this command, <PRIOR_RANCHER_VERSION> is the version of Rancher you were running before your unsuccessful upgrade. v2.0.5 for example.

        Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

        Terminal docker ps Command, Displaying Where to Find <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME>![Placeholder Reference](/img/placeholder-ref-2.png)
        PlaceholderExampleDescription
        <PRIOR_RANCHER_VERSION>v2.0.5The rancher/rancher image you used before upgrade.
        <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
        <RANCHER_VERSION>v2.0.5The version of Rancher that the backup is for.
        <DATE>9-27-18The date that the data container or backup was created.

        You can obtain <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

        Rolling Back Rancher​

        If you have issues upgrading Rancher, roll it back to its latest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade.

        Warning! Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur.

        1. Using a remote Terminal connection, log into the node running your Rancher Server.

        2. Pull the version of Rancher that you were running before upgrade. Replace the <PRIOR_RANCHER_VERSION> with that version.

          For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5.

          docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

        3. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

          docker stop <RANCHER_CONTAINER_NAME>

          You can obtain the name for your Rancher container by entering docker ps.

        4. Move the backup tarball that you created during completion of Docker Upgrade onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

          If you followed the naming convention we suggested in Docker Upgrade, it will have a name similar to (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

        5. Run the following command to replace the data in the rancher-data container with the data in the backup tarball, replacing the placeholder. Don't forget to close the quotes.

          docker run  --volumes-from rancher-data \
          -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \
          && tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

        6. Start a new Rancher Server container with the <PRIOR_RANCHER_VERSION> tag placeholder pointing to the data container.

          docker run -d --volumes-from rancher-data \
          --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          rancher/rancher:<PRIOR_RANCHER_VERSION>

          Note: Do not stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades.

        7. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored.

        Result: Rancher is rolled back to its version and data state before upgrade.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html index 6fdc40632b5..3bb9dc8e56c 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html @@ -5,13 +5,13 @@ Upgrading Rancher Installed with Docker | Rancher Manager - +
        Version: v2.0-v2.4

        Upgrading Rancher Installed with Docker

        The following instructions will guide you through upgrading a Rancher server that was installed with Docker.

        Prerequisites

        Placeholder Review

        During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>).

        Here's an example of a command with a placeholder:

        docker stop <RANCHER_CONTAINER_NAME>

        In this command, <RANCHER_CONTAINER_NAME> is the name of your Rancher container.

        Get Data for Upgrade Commands

        To obtain the data to replace the placeholders, run:

        docker ps

        Write down or copy this information before starting the upgrade.

        Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

        Placeholder Reference

        PlaceholderExampleDescription
        <RANCHER_CONTAINER_TAG>v2.1.3The rancher/rancher image you pulled for initial install.
        <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
        <RANCHER_VERSION>v2.1.3The version of Rancher that you're creating a backup for.
        <DATE>2018-12-19The date that the data container or backup was created.

        You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

        Upgrade Outline

        During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server:

        1. Create a copy of the data from your Rancher server container

        1. Using a remote Terminal connection, log into the node running your Rancher server.

        2. Stop the container currently running Rancher server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

          docker stop <RANCHER_CONTAINER_NAME>
        3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
          docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>

        2. Create a backup tarball

        1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

          This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder.

        ```
        docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
        ```

        **Step Result:** When you enter this command, a series of commands should run.

        1. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

          [rancher@ip-10-0-0-50 ~]$ ls
          rancher-data-backup-v2.1.3-20181219.tar.gz

        2. Move your backup tarball to a safe location external from your Rancher server.

        3. Pull the New Docker Image

        Pull the image of the Rancher version that you want to upgrade to.

        PlaceholderDescription
        <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
        docker pull rancher/rancher:<RANCHER_VERSION_TAG>

        4. Start the New Rancher Server Container

        Start a new Rancher server container using the data from the rancher-data container. Remember to pass in all the environment variables that you had used when you started the original container.

        Important: Do not stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades.

        If you used a proxy, see HTTP Proxy Configuration.

        If you configured a custom CA root certificate to access your services, see Custom CA root certificate.

        If you are recording all transactions with the Rancher API, see API Auditing

        To see the command to use when starting the new Rancher server container, choose from the following options:

        • Docker Upgrade
        • Docker Upgrade for Air Gap Installs

        Select which option you had installed Rancher server

        Option A: Default Self-Signed Certificate​

        Click to expand

        If you have selected to use the Rancher generated self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container.

        PlaceholderDescription
        <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
        docker run -d --volumes-from rancher-data \
          --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          rancher/rancher:<RANCHER_VERSION_TAG>

        Option B: Bring Your Own Certificate: Self-Signed​

        Click to expand

        If you have selected to bring your own self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with.

        Reminder of the Cert Prerequisite: The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.

        PlaceholderDescription
        <CERT_DIRECTORY>The path to the directory containing your certificate files.
        <FULL_CHAIN.pem>The path to your full certificate chain.
        <PRIVATE_KEY.pem>The path to the private key for your certificate.
        <CA_CERTS.pem>The path to the certificate authority's certificate.
        <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
        docker run -d --volumes-from rancher-data \
          --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
          -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
          -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
          rancher/rancher:<RANCHER_VERSION_TAG>

        Option C: Bring Your Own Certificate: Signed by Recognized CA​

        Click to expand

        If you have selected to use a certificate signed by a recognized CA, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include --no-cacerts as an argument to the container to disable the default CA certificate generated by Rancher.

        Reminder of the Cert Prerequisite: The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

        PlaceholderDescription
        <CERT_DIRECTORY>The path to the directory containing your certificate files.
        <FULL_CHAIN.pem>The path to your full certificate chain.
        <PRIVATE_KEY.pem>The path to the private key for your certificate.
        <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
        docker run -d --volumes-from rancher-data \
          --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
          -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
          rancher/rancher:<RANCHER_VERSION_TAG> \
          --no-cacerts

        Option D: Let's Encrypt Certificate​

        Click to expand

        Remember: Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

        If you have selected to use Let's Encrypt certificates, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher.

        Reminder of the Cert Prerequisites:

        • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
        • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.
        PlaceholderDescription
        <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
        <YOUR.DNS.NAME>The domain address that you had originally started with
        docker run -d --volumes-from rancher-data \
          --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          rancher/rancher:<RANCHER_VERSION_TAG> \
          --acme-domain <YOUR.DNS.NAME>

        Result: You have upgraded Rancher. Data from your upgraded server is now saved to the rancher-data container for use in future upgrades.

        5. Verify the Upgrade

        Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window.

        Having network issues in your user clusters following upgrade?

        See Restoring Cluster Networking.

        6. Clean up Your Old Rancher Server Container

        Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.

        Rolling Back

        If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see Docker Rollback.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.html index febaca096e3..623ae6e7cd9 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/add-tls-secrets.html @@ -5,14 +5,14 @@ Adding TLS Secrets | Rancher Manager - +
        Version: v2.0-v2.4

        Adding TLS Secrets

        Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the tls-rancher-ingress secret in the cattle-system namespace with the certificate and key.

        Combine the server certificate followed by any intermediate certificate(s) needed into a file named tls.crt. Copy your certificate key into a file named tls.key.

        For example, acme.sh provides server certificate and CA chains in fullchain.cer file. This fullchain.cer should be renamed to tls.crt & certificate key file as tls.key.

        Use kubectl with the tls secret type to create the secrets.

        kubectl -n cattle-system create secret tls tls-rancher-ingress \
          --cert=tls.crt \
          --key=tls.key

        Note: If you want to replace the certificate, you can delete the tls-rancher-ingress secret using kubectl -n cattle-system delete secret tls-rancher-ingress and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.

        Using a Private CA Signed Certificate

        If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.

        Copy the CA certificate into a file named cacerts.pem and use kubectl to create the tls-ca secret in the cattle-system namespace.

        kubectl -n cattle-system create secret generic tls-ca \
          --from-file=cacerts.pem=./cacerts.pem

        Note: The configured tls-ca secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started.

        Updating a Private CA Certificate

        Follow the steps on this page to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html index baf4044cd5c..68a28b58a7b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html @@ -5,7 +5,7 @@ Choosing a Rancher Version | Rancher Manager - + @@ -14,7 +14,7 @@     helm search repo --versions

        If you have several repos you can specify the repo name, ie. helm search repo rancher-stable/rancher --versions
        For more information, see https://helm.sh/docs/helm/helm_search_repo/

        To fetch a specific version of your chosen repo, define the --version parameter like in the following example:
            helm fetch rancher-stable/rancher --version=2.4.8

        For the Rancher v2.1.x versions, there were some Helm charts where the version was a build number, i.e. yyyy.mm.<build-number>. These charts have been replaced with the equivalent Rancher version and are no longer available.

        Switching to a Different Helm Chart Repository​

        After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps.

        Note: Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported.

        • Latest: Recommended for trying out the newest features
          helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
        • Stable: Recommended for production environments
          helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
        • Alpha: Experimental preview of upcoming releases.
          helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
          Note: Upgrades are not supported to, from, or between Alphas.

        1. List the current Helm chart repositories.

          helm repo list

          NAME                  URL
          stable                https://charts.helm.sh/stable
          rancher-<CHART_REPO>        https://releases.rancher.com/server-charts/<CHART_REPO>

        2. Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be rancher-stable or rancher-latest depending on what you had initially added.

          helm repo remove rancher-<CHART_REPO>

        3. Add the Helm chart repository that you want to start installing Rancher from.

          helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>

        4. Continue to follow the steps to upgrade Rancher from the new Helm chart repository.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html index 0e107fc0c74..c34e06b9a18 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html @@ -5,13 +5,13 @@ About Custom CA Root Certificates | Rancher Manager - +
        Version: v2.0-v2.4

        About Custom CA Root Certificates

        If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).

        Services that Rancher needs to access are sometimes configured with a certificate from a custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: x509: certificate signed by unknown authority.

        To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable SSL_CERT_DIR to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (-v host-source-directory:container-destination-directory) when starting the Rancher container.

        Examples of services that Rancher can access:

        • Catalogs
        • Authentication providers
        • Accessing hosting/cloud API when using Node Drivers

        Installing with the custom CA Certificate​

        For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs:

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/helm-version-requirements.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/helm-version-requirements.html index 0ff2db023c3..4e05760f683 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/helm-version-requirements.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/helm-version-requirements.html @@ -5,13 +5,13 @@ Helm Version Requirements | Rancher Manager - +
        Version: v2.0-v2.4

        Helm Version Requirements

        This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.

        The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 Migration Docs. This section provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

        • Helm v2.16.0 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the release notes for the version of RKE that you are using.
        • Helm v2.15.0 should not be used, because of an issue with converting/comparing numbers.
        • Helm v2.12.0 should not be used, because of an issue with cert-manager.
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/local-system-charts.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/local-system-charts.html index 51383db74c4..bfd6f95458b 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/local-system-charts.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/local-system-charts.html @@ -5,13 +5,13 @@ Setting up Local System Charts for Air Gapped Installations | Rancher Manager - +
        Version: v2.0-v2.4

        Setting up Local System Charts for Air Gapped Installations

        The System Charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS.

        In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag in Rancher v2.3.0, and using a Git mirror for Rancher versions before v2.3.0.

        Using Local System Charts in Rancher v2.3.0

        In Rancher v2.3.0, a local copy of system-charts has been packaged into the rancher/rancher container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, CATTLE_SYSTEM_CATALOG=bundled, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub.

        Example commands for a Rancher installation with a bundled system-charts are included in the air gap Docker installation instructions and the air gap Kubernetes installation instructions.

        Setting Up System Charts for Rancher Before v2.3.0

        A. Prepare System Charts​

        The System Charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the system-charts repository to a location in your network that Rancher can reach and configure Rancher to use that repository.

        Refer to the release notes in the system-charts repository to see which branch corresponds to your version of Rancher.

        B. Configure System Charts​

        Rancher needs to be configured to use your Git mirror of the system-charts repository. You can configure the system charts repository either from the Rancher UI or from Rancher's API view.

        In the catalog management page in the Rancher UI, follow these steps:

        1. Go to the Global view.

        2. Click Tools > Catalogs.

        3. The system chart is displayed under the name system-library. To edit the configuration of the system chart, click ⋮ > Edit.

        4. In the Catalog URL field, enter the location of the Git mirror of the system-charts repository.

        5. Click Save.

        Result: Rancher is configured to download all the required catalog items from your system-charts repository.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html index 2e9e7600d2b..caa84da53e7 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html @@ -5,14 +5,14 @@ Updating the Rancher Certificate | Rancher Manager - +
        Version: v2.0-v2.4

        Updating a Private CA Certificate

        Follow these steps to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

        A summary of the steps is as follows:

        1. Create or update the tls-rancher-ingress Kubernetes secret resource with the new certificate and private key.
        2. Create or update the tls-ca Kubernetes secret resource with the root CA certificate (only required when using a private CA).
        3. Update the Rancher installation using the Helm CLI.
        4. Reconfigure the Rancher agents to trust the new CA certificate.

        The details of these instructions are below.

        1. Create/update the certificate secret resource​

        First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

        If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

        $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
          --cert=tls.crt \
          --key=tls.key

        Alternatively, to update an existing certificate secret:

        $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
          --cert=tls.crt \
          --key=tls.key \
          --dry-run --save-config -o yaml | kubectl apply -f -

        2. Create/update the CA certificate secret resource​

        If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named cacerts.pem and create or update the tls-ca secret in the cattle-system namespace. If the certificate was signed by an intermediate CA, then the cacerts.pem must contain both the intermediate and root CA certificates (in this order).

        To create the initial secret:

        $ kubectl -n cattle-system create secret generic tls-ca \
          --from-file=cacerts.pem

        To update an existing tls-ca secret:

        $ kubectl -n cattle-system create secret generic tls-ca \
          --from-file=cacerts.pem \
          --dry-run --save-config -o yaml | kubectl apply -f -

        3. Reconfigure the Rancher deployment​

        Before proceeding, generate an API token in the Rancher UI (User > API & Keys).

        This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

        It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

        To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

        $ helm get values rancher -n cattle-system

        Also get the version string of the currently deployed Rancher chart:

        $ helm ls -A

        Upgrade the Helm application instance using the original configuration values and making sure to specify ingress.tls.source=secret as well as the current chart version to prevent an application upgrade.

        If the certificate was signed by a private CA, add the set privateCA=true argument as well. Also make sure to read the documentation describing the initial installation using custom certificates.

        helm upgrade rancher rancher-stable/rancher \
          --namespace cattle-system \
          --version <DEPLOYED_CHART_VERSION> \
          --set hostname=rancher.my.org \
          --set ingress.tls.source=secret \
          --set ...

        When the upgrade is completed, navigate to https://<Rancher_SERVER>/v3/settings/cacerts to verify that the value matches the CA certificate written in the tls-ca secret earlier.

        4. Reconfigure Rancher agents to trust the private CA​

        This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true:

        • Rancher was initially configured to use the Rancher self-signed certificate (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt)
        • The root CA certificate for the new custom certificate has changed

        Why is this step required?​

        When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the CATTLE_CA_CHECKSUM environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable CATTLE_CA_CHECKSUM must be updated accordingly.

        Which method should I choose?​

        Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3).

        If the clusters have lost connection to Rancher but you have Authorized Cluster Endpoints enabled, then go with method 2.

        Method 3 can be used as a fallback if method 1 and 2 are unfeasible.

        Method 1: Kubectl command​

        For each cluster under Rancher management (including local) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S).

        kubectl patch clusters <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge

        This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate.

        Method 2: Manually update checksum​

        Manually patch the agent Kubernetes resources by updating the CATTLE_CA_CHECKSUM environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:

        $ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
        $ sha256sum cacert.tmp | awk '{print $1}'

        Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments.

        $ kubectl edit -n cattle-system ds/cattle-node-agent
        $ kubectl edit -n cattle-system deployment/cluster-agent

        Method 3: Recreate Rancher agents​

        With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster.

        First, generate the agent definitions as described here: https://gist.github.com/superseb/076f20146e012f1d4e289f5bd1bd4971

        Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions: https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b

        Updating from a Private CA Certificate to a Common Certificate

        It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below.

        1. Create/update the certificate secret resource​

        First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

        If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

        $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
          --cert=tls.crt \
          --key=tls.key

        Alternatively, to update an existing certificate secret:

        $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
          --cert=tls.crt \
          --key=tls.key \
          --dry-run --save-config -o yaml | kubectl apply -f -

        2. Delete the CA certificate secret resource​

        You will delete the tls-ca secret in the cattle-system namespace as it is no longer needed. You may also optionally save a copy of the tls-ca secret if desired.

        To save the existing secret:

        kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml

        To delete the existing tls-ca secret:

        kubectl -n cattle-system delete secret tls-ca

        3. Reconfigure the Rancher deployment​

        Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4.

        This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

        It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

        To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

        $ helm get values rancher -n cattle-system

        Also get the version string of the currently deployed Rancher chart:

        $ helm ls -A

        Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.

        Also make sure to read the documentation describing the initial installation using custom certificates.

        helm upgrade rancher rancher-stable/rancher \
          --namespace cattle-system \
          --version <DEPLOYED_CHART_VERSION> \
          --set hostname=rancher.my.org \
          --set ...

        On upgrade, you can either

        • remove --set ingress.tls.source=secret \ from the Helm upgrade command, as shown above, or

        • remove the privateCA parameter or set it to false because the CA is valid:

        set privateCA=false

        4. Reconfigure Rancher agents for the non-private/common certificate​

        CATTLE_CA_CHECKSUM environment variable on the downstream cluster agents should be removed or set to "" (an empty string).

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html index ad2519d60a9..e9c57a097d4 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html @@ -5,7 +5,7 @@ Upgrading Cert-Manager with Helm 2 | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        Upgrading Cert-Manager with Helm 2

        Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:

        1. Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.
        2. Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field. This change has no exact deadline.
        3. Cert-manager is deprecating v1alpha1 API and replacing its API group

        To address these changes, this guide will do two things:

        1. Document the procedure for upgrading cert-manager
        2. Explain the cert-manager API changes and link to cert-manager's offficial documentation for migrating your data

        Important: If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them:

        1. Take a one-time snapshot of your Kubernetes cluster running Rancher server
        2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager
        3. Install the newer version of Rancher and cert-manager

        The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.

        For reinstalling Rancher with Helm, please check Option B: Reinstalling Rancher Chart under the upgrade Rancher section.

        Upgrade Cert-Manager Only​

        Note: These instructions are applied if you have no plan to upgrade Rancher.

        The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running kubectl get pods --all-namespaces and checking which namespace the cert-manager-* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues.

        In order to upgrade cert-manager, follow these instructions:

        Upgrading cert-manager with Internet access
        1. Back up existing resources as a precaution
        ```plain
        kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml
        ```

        1. Delete the existing deployment

          helm delete --purge cert-manager

        2. Install the CustomResourceDefinition resources separately

          kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml

        3. Add the Jetstack Helm repository

          helm repo add jetstack https://charts.jetstack.io

        4. Update your local Helm chart repository cache

          helm repo update

        5. Install the new version of cert-manager

          helm install --version 0.12.0 --name cert-manager --namespace kube-system jetstack/cert-manager
        Upgrading cert-manager in an airgapped environment

        Prerequisites​

        Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.

        1. Follow the guide to Prepare your Private Registry with the images needed for the upgrade.

        2. From a system connected to the internet, add the cert-manager repo to Helm

          helm repo add jetstack https://charts.jetstack.io
          helm repo update

        3. Fetch the latest cert-manager chart available from the Helm chart repository.

          helm fetch jetstack/cert-manager --version v0.12.0

        4. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

          helm template ./cert-manager-v0.12.0.tgz --output-dir . \
          --name cert-manager --namespace kube-system \
          --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
          --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
          --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

        5. Download the required CRD file for cert-manager

          curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml

        Install cert-manager​

        1. Back up existing resources as a precaution

          kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml

        2. Delete the existing cert-manager installation

          kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

        3. Install the CustomResourceDefinition resources separately

          kubectl apply -f cert-manager/cert-manager-crd.yaml

        1. Install cert-manager

          kubectl -n kube-system apply -R -f ./cert-manager

        Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:

        kubectl get pods --namespace kube-system

        NAME                                            READY   STATUS      RESTARTS   AGE
        cert-manager-7cbdc48784-rpgnt                   1/1     Running     0          3m
        cert-manager-webhook-5b5dd6999-kst4x            1/1     Running     0          3m
        cert-manager-cainjector-3ba5cd2bcd-de332x       1/1     Running     0          3m

        If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's troubleshooting guide.

        Note: The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary:

        Cert-Manager API change and data migration​

        Cert-manager has deprecated the use of the certificate.spec.acme.solvers field and will drop support for it completely in an upcoming release.

        Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.

        Details about the change and migration instructions can be found in the cert-manager v0.7 to v0.8 upgrade instructions.

        The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.

        We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the upgrading to v0.8 guide.

        Details about the change and migration instructions can be found in the cert-manager v0.10 to v0.11 upgrade instructions.

        For information on upgrading from all other versions of cert-manager, refer to the official documentation.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html index 1ca26fd9ab5..5d7501bcfe1 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html @@ -5,7 +5,7 @@ Upgrading Cert-Manager | Rancher Manager - + @@ -15,7 +15,7 @@ If you are currently running the cert-manager whose version is older than v0.11, If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

      • Create the namespace for cert-manager if needed

        kubectl create namespace cert-manager

      • Add the Jetstack Helm repository

        helm repo add jetstack https://charts.jetstack.io

      • Update your local Helm chart repository cache

        helm repo update

      • Install the new version of cert-manager

        helm install \
          cert-manager jetstack/cert-manager \
          --namespace cert-manager \
          --version v0.12.0

      • Restore back up resources

        kubectl apply -f cert-manager-backup.yaml

        • Option B: Upgrade cert-manager in an Air Gap Environment​

        Click to expand

        Prerequisites​

        Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.

        1. Follow the guide to Prepare your Private Registry with the images needed for the upgrade.

        2. From a system connected to the internet, add the cert-manager repo to Helm

          helm repo add jetstack https://charts.jetstack.io
          helm repo update

        3. Fetch the latest cert-manager chart available from the Helm chart repository.

          helm fetch jetstack/cert-manager --version v0.12.0

        4. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

          The Helm 3 command is as follows:

          helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \
          --namespace cert-manager \
          --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
          --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
          --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

          The Helm 2 command is as follows:

          helm template ./cert-manager-v0.12.0.tgz --output-dir . \
          --name cert-manager --namespace cert-manager \
          --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
          --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
          --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

        5. Download the required CRD file for cert-manager (old and new)

          curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
          curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml

        Install cert-manager​

        1. Back up existing resources as a precaution

          kubectl get -o yaml --all-namespaces \
          issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml

          Important: If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from certmanager.k8s.io/v1alpha1 to cert-manager.io/v1alpha2. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on additional annotation changes.

        2. Delete the existing cert-manager installation

          kubectl -n cert-manager \
          delete deployment,sa,clusterrole,clusterrolebinding \
          -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

          Delete the CustomResourceDefinition using the link to the version vX.Y you installed

          kubectl delete -f cert-manager/cert-manager-crd-old.yaml

        3. Install the CustomResourceDefinition resources separately

          kubectl apply -f cert-manager/cert-manager-crd.yaml

          Note: If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

        4. Create the namespace for cert-manager

          kubectl create namespace cert-manager

        5. Install cert-manager

          kubectl -n cert-manager apply -R -f ./cert-manager

        6. Restore back up resources

          kubectl apply -f cert-manager-backup.yaml

        Verify the Deployment​

        Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:

        kubectl get pods --namespace cert-manager

        NAME                                       READY   STATUS    RESTARTS   AGE
        cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
        cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
        cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

        Cert-Manager API change and data migration​

        Cert-manager has deprecated the use of the certificate.spec.acme.solvers field and will drop support for it completely in an upcoming release.

        Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.

        Details about the change and migration instructions can be found in the cert-manager v0.7 to v0.8 upgrade instructions.

        The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.

        We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the upgrading to v0.8 guide.

        Details about the change and migration instructions can be found in the cert-manager v0.10 to v0.11 upgrade instructions.

        More info about cert-manager upgrade information.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html b/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html index ccc1601f269..3952a527051 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html @@ -5,13 +5,13 @@ Upgrading and Rolling Back Kubernetes | Rancher Manager - +
        Version: v2.0-v2.4

        Upgrading and Rolling Back Kubernetes

        Following an upgrade to the latest version of Rancher, downstream Kubernetes clusters can be upgraded to use the latest supported version of Kubernetes.

        Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the RKE documentation.

        New Features

        As of Rancher v2.3.0, the Kubernetes metadata feature was added, which allows Rancher to ship Kubernetes patch versions without upgrading Rancher. For details, refer to the section on Kubernetes metadata.

        As of Rancher v2.4.0,

        • The ability to import K3s Kubernetes clusters into Rancher was added, along with the ability to upgrade Kubernetes when editing those clusters. For details, refer to the section on imported clusters.
        • New advanced options are exposed in the Rancher UI for configuring the upgrade strategy of an RKE cluster: Maximum Worker Nodes Unavailable and Drain nodes. These options leverage the new cluster upgrade process of RKE v1.1.0, in which worker nodes are upgraded in batches, so that applications can remain available during cluster upgrades, under certain conditions.

        Tested Kubernetes Versions

        Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the support maintenance terms.

        How Upgrades Work

        RKE v1.1.0 changed the way that clusters are upgraded.

        In this section of the RKE documentation, you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster.

        Recommended Best Practice for Upgrades

        When upgrading the Kubernetes version of a cluster, we recommend that you:

        1. Take a snapshot.
        2. Initiate a Kubernetes upgrade.
        3. If the upgrade fails, revert the cluster to the pre-upgrade Kubernetes version. This is achieved by selecting the Restore etcd and Kubernetes version option. This will return your cluster to the pre-upgrade kubernetes version before restoring the etcd snapshot.

        The restore operation will work on a cluster that is not in a healthy or active state.

        Upgrading the Kubernetes Version

        Prerequisites:

        1. From the Global view, find the cluster for which you want to upgrade Kubernetes. Select ⋮ > Edit.

        2. Expand Cluster Options.

        3. From the Kubernetes Version drop-down, choose the version of Kubernetes that you want to use for the cluster.

        4. Click Save.

        Result: Kubernetes begins upgrading for the cluster.

        Rolling Back

        Available as of v2.4

        A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections:

        Configuring the Upgrade Strategy

        As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain conditions and requirements are met.

        The upgrade strategy can be configured in the Rancher UI, or by editing the cluster.yml. More advanced options are available by editing the cluster.yml.

        Configuring the Maximum Unavailable Worker Nodes in the Rancher UI​

        From the Rancher UI, the maximum number of unavailable worker nodes can be configured. During a cluster upgrade, worker nodes will be upgraded in batches of this size.

        By default, the maximum number of unavailable worker is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node.

        To change the default number or percentage of worker nodes,

        1. Go to the cluster view in the Rancher UI.
        2. Click ⋮ > Edit.
        3. In the Advanced Options section, go to the Maxiumum Worker Nodes Unavailable field. Enter the percentage of worker nodes that can be upgraded in a batch. Optionally, select Count from the drop-down menu and enter the maximum unavailable worker nodes as an integer.
        4. Click Save.

        Result: The cluster is updated to use the new upgrade strategy.

        Enabling Draining Nodes During Upgrades from the Rancher UI​

        By default, RKE cordons each node before upgrading it. Draining is disabled during upgrades by default. If draining is enabled in the cluster configuration, RKE will both cordon and drain the node before it is upgraded.

        To enable draining each node during a cluster upgrade,

        1. Go to the cluster view in the Rancher UI.
        2. Click ⋮ > Edit.
        3. In the Advanced Options section, go to the Drain nodes field and click Yes.
        4. Choose a safe or aggressive drain option. For more information about each option, refer to this section.
        5. Optionally, configure a grace period. The grace period is the timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. Pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If this value is negative, the default value specified in the pod will be used.
        6. Optionally, configure a timeout, which is the amount of time the drain should continue to wait before giving up.
        7. Click Save.

        Result: The cluster is updated to use the new upgrade strategy.

        Note: As of Rancher v2.4.0, there is a known issue in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.

        Maintaining Availability for Applications During Upgrades​

        Available as of RKE v1.1.0

        In this section of the RKE documentation, you'll learn the requirements to prevent downtime for your applications when upgrading the cluster.

        Configuring the Upgrade Strategy in the cluster.yml​

        More advanced upgrade strategy configuration options are available by editing the cluster.yml.

        For details, refer to Configuring the Upgrade Strategy in the RKE documentation. The section also includes an example cluster.yml for configuring the upgrade strategy.

        Troubleshooting

        If a node doesn't come up after an upgrade, the rke up command errors out.

        No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum.

        If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue.

        A failed node could be in many different states:

        • Powered off
        • Unavailable
        • User drains a node while upgrade is in process, so there are no kubelets on the node
        • The upgrade itself failed

        If the max unavailable number of nodes is reached during an upgrade, Rancher user clusters will be stuck in updating state and not move forward with upgrading any other control plane nodes. It will continue to evaluate the set of unavailable nodes in case one of the nodes becomes available. If the node cannot be fixed, you must remove the node in order to continue the upgrade.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html b/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html index 6f410a93890..463215fac61 100644 --- a/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html +++ b/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html @@ -5,13 +5,13 @@ Upgrading Kubernetes without Upgrading Rancher | Rancher Manager - +
        Version: v2.0-v2.4

        Upgrading Kubernetes without Upgrading Rancher

        Available as of v2.3.0

        The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.

        Note: The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.

        Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision RKE clusters. Rancher syncs the data periodically and creates custom resource definitions (CRDs) for system images, service options and addon templates. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the Rancher Kubernetes Engine (RKE) uses for deploying various Kubernetes versions.

        This table below describes the CRDs that are affected by the periodic data sync.

        Note: Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.

        ResourceDescriptionRancher API URL
        System ImagesList of system images used to deploy Kubernetes through RKE.<RANCHER_SERVER_URL>/v3/rkek8ssystemimages
        Service OptionsDefault options passed to Kubernetes components like kube-api, scheduler, kubelet, kube-proxy, and kube-controller-manager<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions
        Addon TemplatesYAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, metrics-server, nginx-ingress<RANCHER_SERVER_URL>/v3/rkeaddons

        Administrators might configure the RKE metadata settings to do the following:

        • Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher
        • Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
        • Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher

        Refresh Kubernetes Metadata​

        The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the Manage Cluster Drivers global role.

        To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available under Tools > Drivers > Refresh Kubernetes Metadata on the right side corner.

        You can configure Rancher to only refresh metadata when desired by setting refresh-interval-minutes to 0 (see below) and using this button to perform the metadata refresh manually when desired.

        Configuring the Metadata Synchronization​

        Only administrators can change these settings.

        The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint v3/settings/rke-metadata-config.

        The way that the metadata is configured depends on the Rancher version.

        To edit the metadata config in Rancher,

        1. Go to the Global view and click the Settings tab.
        2. Go to the rke-metadata-config section. Click the ⋮ and click Edit.
        3. You can optionally fill in the following parameters:
        • refresh-interval-minutes: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set refresh-interval-minutes to 0.
        • url: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json.

        If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from Rancher's metadata Git repository.

        However, if you have an air gap setup, you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.

        Air Gap Setups​

        Rancher relies on a periodic refresh of the rke-metadata-config to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the service terms section.

        If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.

        To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the rke-metadata-config settings to point to the mirror. For details, refer to Configuring the Metadata Synchronization.

        After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.

        1. To download the system images for the private registry, click the Rancher server version at the bottom left corner of the Rancher UI.
        2. Download the OS specific image lists for Linux or Windows.
        3. Download rancher-images.txt.
        4. Prepare the private registry using the same steps during the air gap install, but instead of using the rancher-images.txt from the releases page, use the one obtained from the previous steps.

        Result: The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/introduction/overview.html b/v2.0-v2.4/getting-started/introduction/overview.html index 43500690645..6162029f609 100644 --- a/v2.0-v2.4/getting-started/introduction/overview.html +++ b/v2.0-v2.4/getting-started/introduction/overview.html @@ -5,13 +5,13 @@ Overview | Rancher Manager - +
        Version: v2.0-v2.4

        Overview

        Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams.

        Run Kubernetes Everywhere

        Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer.

        Meet IT requirements

        Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can:

        • Use your Active Directory credentials to access Kubernetes clusters hosted by cloud vendors, such as GKE.
        • Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds.
        • View the health and capacity of your Kubernetes clusters from a single-pane-of-glass.

        Empower DevOps Teams

        Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers.

        The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds.

        Platform

        Features of the Rancher API Server

        The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:

        Authorization and Role-Based Access Control​

        • User management: The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub, in addition to local users.
        • Authorization: The Rancher API server manages access control and security policies.

        Working with Kubernetes​

        • Provisioning Kubernetes clusters: The Rancher API server can provision Kubernetes on existing nodes, or perform Kubernetes upgrades.
        • Catalog management: Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications.
        • Managing projects: A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for project administration and for managing applications within projects.
        • Pipelines: Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects.
        • Istio: Our integration with Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

        Working with Cloud Infrastructure​

        • Tracking nodes: The Rancher API server tracks identities of all the nodes in all clusters.
        • Setting up infrastructure: When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud.

        Cluster Visibility​

        • Logging: Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters.
        • Monitoring: Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.
        • Alerting: To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned.

        Editing Downstream Clusters with Rancher

        The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters provisioned by RKE have Cluster Options available for editing.

        After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among other options.

        The following table summarizes the options and settings available for each cluster type:

        ActionRancher launched Kubernetes ClustersHosted Kubernetes ClustersImported Clusters
        Using kubectl and a kubeconfig file to Access a Cluster✓✓✓
        Managing Cluster Members✓✓✓
        Editing and Upgrading Clusters✓✓*
        Managing Nodes✓✓✓
        Managing Persistent Volumes and Storage Classes✓✓✓
        Managing Projects, Namespaces and Workloads✓✓✓
        Using App Catalogs✓✓✓
        Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓
        Cloning Clusters✓✓
        Ability to rotate certificates✓
        Ability to back up your Kubernetes Clusters✓
        Ability to recover and restore etcd✓
        Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
        Configuring Pod Security Policies✓
        Running Security Scans✓
        Authorized Cluster Endpoint✓

        * Cluster configuration options can't be edited for imported clusters, except for K3s clusters.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/introduction/what-are-divio-docs.html b/v2.0-v2.4/getting-started/introduction/what-are-divio-docs.html index 6ce4ca9b80f..1e33d3d2a58 100644 --- a/v2.0-v2.4/getting-started/introduction/what-are-divio-docs.html +++ b/v2.0-v2.4/getting-started/introduction/what-are-divio-docs.html @@ -5,13 +5,13 @@ What Are Divio Docs? | Rancher Manager - +
        Version: v2.0-v2.4

        What Are Divio Docs?

        The Divio documentation system is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.

        In our docs, we have used this guideline to craft a unique set of docs which include getting started, how-to guides (including new and advanced user guides), reference guides, explanations, an FAQ section, troubleshooting tips, and the ability to contribute to Rancher.

        Getting Started​

        To get up and running with Rancher quickly, we have included a Getting Started section.

        The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

        Please see the introduction, quick start guides, and the installation and upgrade sections for more.

        How-to Guides​

        How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

        New User Guides​

        New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

        The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

        The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

        A good example of a new user guide can be found here.

        Advanced User Guides​

        Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.

        It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

        A good example of an advanced user guide can be found here.

        Reference Guides​

        Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

        These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

        The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

        Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

        Explanations​

        Explanation docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

        Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.

        For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature Integrations in Rancher to discuss our integrated products.

        Integrations in Rancher​

        Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under Explanations.

        Examples of some of these integrations are Istio and CIS Scans.

        Other Docs Categories​

        FAQ​

        Our FAQ section is designed to answer the questions our users have been most often asking about Rancher v2.x. The nature of these questions may be technical or non-technical.

        We work to continually add to and enhance this section; check back frequently for updates.

        Troubleshooting​

        The troubleshooting section is designed to help both new and existing Rancher users to troubleshoot known issues that they may encounter when using Rancher.

        We work to continually add to and enhance this section; check back frequently for updates.

        Contribute to Rancher​

        The Rancher Manager documentation is always a work-in-progress; the docs work best when being constantly examined, updated, and improved upon. To do this more effectively, we call upon the community to assist us.

        This contributing to Rancher section will instruct users on the repositories used for Rancher, how to build the repositories, and what information is needed when filing an issue or creating a pull request.

        We review all contributions frequently and will provide feedback to contributors promptly.

        Overlapping of Categories​

        You may have noticed that within the confines of each category - new user guides, advanced user guides, references - there is some overlap. This is true because the flow of information is fluid, and so often docs will include data that could logically fall under more than one category. Although there is the tendency for our docs to overlap somewhat, if we keep in mind the primary functions of each category and work to make those distinct, then the documentation will be much clearer and useful for users.

        New Structure Goals​

        Our previous Rancher documentation focused on individual features and topics; the new Divio paradigm prioritizes function and cohesion.

        Because the previous docs structure was not based on the Divio paradigm, not every doc as it is written currently will fall neatly into a user guide or a reference, for example. Some docs may include elements of several kind of documentation functions.

        As such, we have worked to move our existing documentation into the new paradigm based on each doc's function. Moving forward, we will be creating, rewriting, and reshaping our docs as needed to more closely align with the Divio structure, purpose, and its design concepts.

        Ultimately, the finished product will much more cohesively and effectively assist our users by emphasizing functionality over individual topic or feature-based docs.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/cli.html b/v2.0-v2.4/getting-started/quick-start-guides/cli.html index baa2554f880..44c3a393f1b 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/cli.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/cli.html @@ -5,7 +5,7 @@ CLI with Rancher | Rancher Manager - + @@ -15,7 +15,7 @@ The kubeconfig token is cached in the path where you run kubectl under ./.cache/token. This token is valid till it expires, or gets deleted from the Rancher server Upon expiration, the next kubectl get pods will ask you to log in with the Rancher server again.

        Note

        As of CLI v2.4.10, the kubeconfig token can be cached at a chosen path with cache-dir flag or env var RANCHER_CACHE_DIR.

        Current Known Issues

        1. If authorized cluster endpoint is enabled for RKE clusters to authenticate directly with downstream cluster and Rancher server goes down, all kubectl calls will fail after the kubeconfig token expires. No new kubeconfig tokens can be generated if Rancher server isn't accessible.
        2. If a kubeconfig token is deleted from Rancher API tokens page, and the token is still cached, cli won't ask you to login again until the token expires or is deleted. kubectl calls will result into an error like error: You must be logged in to the server (the server has asked for the client to provide credentials. Tokens can be deleted using rancher token delete.
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/aws.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/aws.html index ec1cdf0d56c..8e5e9667c04 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/aws.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/aws.html @@ -5,7 +5,7 @@ Rancher AWS Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Amazon AWS will incur charges.

        • Amazon AWS Account: An Amazon AWS Account is required to create resources for deploying Rancher and Kubernetes.
        • Amazon AWS Access Key: Use this link to follow a tutorial to create an Amazon AWS Access Key if you don't have one yet.
        • Install Terraform: Used to provision the server and cluster in Amazon AWS.

        Getting Started​

        1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

        2. Go into the AWS folder containing the terraform files by executing cd quickstart/aws.

        3. Rename the terraform.tfvars.example file to terraform.tfvars.

        4. Edit terraform.tfvars and customize the following variables:

          • aws_access_key - Amazon AWS Access Key
          • aws_secret_key - Amazon AWS Secret Key
          • rancher_server_admin_password - Admin password for created Rancher server

        5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the AWS Quickstart Readme for more information. Suggestions include:

          - `aws_region` - Amazon AWS region, choose the closest instead of the default
          - `prefix` - Prefix for all created resources
          - `instance_type` - EC2 instance size used, minimum is `t3a.medium` but `t3a.large` or `t3a.xlarge` could be used if within budget

        6. Run terraform init.

        7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

          Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

          Outputs:

          rancher_node_ip = xx.xx.xx.xx
          rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
          workload_node_ip = yy.yy.yy.yy

        8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

        Result​

        Two Kubernetes clusters are deployed into your AWS account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Destroying the Environment​

        1. From the quickstart/aws folder, execute terraform destroy --auto-approve.

        2. Wait for confirmation that all resources have been destroyed.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/azure.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/azure.html index 490bb410432..2c2f90dcfaf 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/azure.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/azure.html @@ -5,7 +5,7 @@ Rancher Azure Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Microsoft Azure will incur charges.

        Getting Started​

        1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

        2. Go into the Azure folder containing the terraform files by executing cd quickstart/azure.

        3. Rename the terraform.tfvars.example file to terraform.tfvars.

        4. Edit terraform.tfvars and customize the following variables:

          • azure_subscription_id - Microsoft Azure Subscription ID
          • azure_client_id - Microsoft Azure Client ID
          • azure_client_secret - Microsoft Azure Client Secret
          • azure_tenant_id - Microsoft Azure Tenant ID
          • rancher_server_admin_password - Admin password for created Rancher server

        5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the Azure Quickstart Readme for more information. Suggestions include:

          - `azure_location` - Microsoft Azure region, choose the closest instead of the default
          - `prefix` - Prefix for all created resources
          - `instance_type` - Compute instance size used, minimum is `Standard_DS2_v2` but `Standard_DS2_v3` or `Standard_DS3_v2` could be used if within budget
          - `ssh_key_file_name` - Use a specific SSH key instead of `~/.ssh/id_rsa` (public key is assumed to be `${ssh_key_file_name}.pub`)

        6. Run terraform init.

        7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

          Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

          Outputs:

          rancher_node_ip = xx.xx.xx.xx
          rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
          workload_node_ip = yy.yy.yy.yy

        8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

        Result​

        Two Kubernetes clusters are deployed into your Azure account, one running Rancher Server and the other ready for experimentation deployments.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Destroying the Environment​

        1. From the quickstart/azure folder, execute terraform destroy --auto-approve.

        2. Wait for confirmation that all resources have been destroyed.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html index 47a5b3007d2..4b8553e7160 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html @@ -5,7 +5,7 @@ Rancher DigitalOcean Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to DigitalOcean will incur charges.

        • DigitalOcean Account: You will require an account on DigitalOcean as this is where the server and cluster will run.
        • DigitalOcean Access Key: Use this link to create a DigitalOcean Access Key if you don't have one.
        • Terraform: Used to provision the server and cluster to DigitalOcean.

        Getting Started​

        1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

        2. Go into the DigitalOcean folder containing the terraform files by executing cd quickstart/do.

        3. Rename the terraform.tfvars.example file to terraform.tfvars.

        4. Edit terraform.tfvars and customize the following variables:

          • do_token - DigitalOcean access key
          • rancher_server_admin_password - Admin password for created Rancher server

        5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the DO Quickstart Readme for more information. Suggestions include:

          - `do_region` - DigitalOcean region, choose the closest instead of the default
          - `prefix` - Prefix for all created resources
          - `droplet_size` - Droplet size used, minimum is `s-2vcpu-4gb` but `s-4vcpu-8gb` could be used if within budget
          - `ssh_key_file_name` - Use a specific SSH key instead of `~/.ssh/id_rsa` (public key is assumed to be `${ssh_key_file_name}.pub`)

        6. Run terraform init.

        7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

          Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

          Outputs:

          rancher_node_ip = xx.xx.xx.xx
          rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
          workload_node_ip = yy.yy.yy.yy

        8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

        Result​

        Two Kubernetes clusters are deployed into your DigitalOcean account, one running Rancher Server and the other ready for experimentation deployments.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Destroying the Environment​

        1. From the quickstart/do folder, execute terraform destroy --auto-approve.

        2. Wait for confirmation that all resources have been destroyed.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html index e633ddb2e54..2ed0f368e3b 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html @@ -5,7 +5,7 @@ Rancher GCP Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Google GCP will incur charges.

        • Google GCP Account: A Google GCP Account is required to create resources for deploying Rancher and Kubernetes.
        • Google GCP Project: Use this link to follow a tutorial to create a GCP Project if you don't have one yet.
        • Google GCP Service Account: Use this link and follow instructions to create a GCP service account and token file.
        • Terraform: Used to provision the server and cluster in Google GCP.

        Getting Started​

        1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

        2. Go into the GCP folder containing the terraform files by executing cd quickstart/gcp.

        3. Rename the terraform.tfvars.example file to terraform.tfvars.

        4. Edit terraform.tfvars and customize the following variables:

          • gcp_account_json - GCP service account file path and file name
          • rancher_server_admin_password - Admin password for created Rancher server

        5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the GCP Quickstart Readme for more information. Suggestions include:

          - `gcp_region` - Google GCP region, choose the closest instead of the default
          - `prefix` - Prefix for all created resources
          - `machine_type` - Compute instance size used, minimum is `n1-standard-1` but `n1-standard-2` or `n1-standard-4` could be used if within budget
          - `ssh_key_file_name` - Use a specific SSH key instead of `~/.ssh/id_rsa` (public key is assumed to be `${ssh_key_file_name}.pub`)

        6. Run terraform init.

        7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

          Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

          Outputs:

          rancher_node_ip = xx.xx.xx.xx
          rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
          workload_node_ip = yy.yy.yy.yy

        8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

        Result​

        Two Kubernetes clusters are deployed into your GCP account, one running Rancher Server and the other ready for experimentation deployments.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Destroying the Environment​

        1. From the quickstart/gcp folder, execute terraform destroy --auto-approve.

        2. Wait for confirmation that all resources have been destroyed.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html index 09c76016342..2dcc60ad57b 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html @@ -5,14 +5,14 @@ Manual Quick Start | Rancher Manager - +
        Version: v2.0-v2.4

        Manual Quick Start

        Howdy Partner! This tutorial walks you through:

        • Installation of Rancher 2.x
        • Creation of your first cluster
        • Deployment of an application, Nginx

        Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

        Quick Start Outline​

        This Quick Start Guide is divided into different tasks for easier consumption.


        ### 1. Provision a Linux Host

        Begin creation of a custom cluster by provisioning a Linux host. Your host can be:

        • A cloud-host virtual machine (VM)

        • An on-prem VM

        • A bare-metal server

          Note: When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration.

          For a full list of port requirements, refer to Docker Installation.

          Provision the host according to our Requirements.

        2. Install Rancher​

        To install Rancher on your host, connect to it and then use a shell to install.

        1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection.

        2. From your shell, enter the following command:

          sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher

        Result: Rancher is installed.

        3. Log In​

        Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations.

        1. Open a web browser and enter the IP address of your host: https://<SERVER_IP>.

          Replace <SERVER_IP> with your host IP address.

        2. When prompted, create a password for the default admin account there cowpoke!

        3. Set the Rancher Server URL. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.

          If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster.


        4. Create the Cluster​

        Welcome to Rancher! You are now able to create your first Kubernetes cluster.

        In this task, you can use the versatile Custom option. This option lets you add any Linux host (cloud-hosted VM, on-prem VM, or bare-metal) to be used in a cluster.

        1. From the Clusters page, click Add Cluster.

        2. Choose Custom.

        3. Enter a Cluster Name.

        4. Skip Member Roles and Cluster Options. We'll tell you about them later.

        5. Click Next.

        6. From Node Role, select all the roles: etcd, Control, and Worker.

        7. Optional: Rancher auto-detects the IP addresses used for Rancher communication and cluster communication. You can override these using Public Address and Internal Address in the Node Address section.

        8. Skip the Labels stuff. It's not important for now.

        9. Copy the command displayed on screen to your clipboard.

        10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

        11. When you finish running the command on your Linux host, click Done.

        Result:

        Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

        You can access your cluster after its state is updated to Active.

        Active clusters are assigned two Projects:

        • Default, containing the default namespace
        • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

        Finished​

        Congratulations! You have created your first cluster.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html index 7963dbef767..2d5ae4da697 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html @@ -5,13 +5,13 @@ Vagrant Quick Start | Rancher Manager - +
        Version: v2.0-v2.4

        Vagrant Quick Start

        The following steps quickly deploy a Rancher Server with a single node cluster attached.

        Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

        Prerequisites​

        • Vagrant: Vagrant is required as this is used to provision the machine based on the Vagrantfile.
        • Virtualbox: The virtual machines that Vagrant provisions need to be provisioned to VirtualBox.
        • At least 4GB of free RAM.

        Note​

        • Vagrant will require plugins to create VirtualBox VMs. Install them with the following commands:

          vagrant plugin install vagrant-vboxmanage

          vagrant plugin install vagrant-vbguest

        Getting Started​

        1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

        2. Go into the folder containing the Vagrantfile by executing cd quickstart/vagrant.

        3. Optional: Edit config.yaml to:

          • Change the number of nodes and the memory allocations, if required. (node.count, node.cpus, node.memory)
          • Change the password of the admin user for logging into Rancher. (admin_password)

        4. To initiate the creation of the environment run, vagrant up --provider=virtualbox.

        5. Once provisioning finishes, go to https://172.22.101.101 in the browser. The default user/password is admin/admin.

        Result: Rancher Server and your Kubernetes cluster is installed on VirtualBox.

        What's Next?​

        Use Rancher to create a deployment. For more information, see Creating Deployments.

        Destroying the Environment​

        1. From the quickstart/vagrant folder execute vagrant destroy -f.

        2. Wait for the confirmation that all resources have been destroyed.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/nodeports.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/nodeports.html index d6397a5e41f..d363d7e5344 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/nodeports.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/nodeports.html @@ -5,13 +5,13 @@ Workload with NodePort Quick Start | Rancher Manager - +
        Version: v2.0-v2.4

        Workload with NodePort Quick Start

        Prerequisite​

        You have a running cluster with at least 1 node.

        1. Deploying a Workload​

        You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

        For this workload, you'll be deploying the application Rancher Hello-World.

        1. From the Clusters page, open the cluster that you just created.

        2. From the main menu of the Dashboard, select Projects/Namespaces.

        3. Open the Project: Default project.

        4. Click Resources > Workloads. In versions before v2.3.0, click Workloads > Workloads.

        5. Click Deploy.

          Step Result: The Deploy Workload page opens.

        6. Enter a Name for your workload.

        7. From the Docker Image field, enter rancher/hello-world. This field is case-sensitive.

        8. From Port Mapping, click Add Port.

        9. From the As a drop-down, make sure that NodePort (On every node) is selected.

          As a dropdown, NodePort (On every node selected)

        10. From the On Listening Port field, leave the Random value in place.

          On Listening Port, Random selected

        11. From the Publish the container port field, enter port 80.

          Publish the container port, 80 entered

        12. Leave the remaining options on their default setting. We'll tell you about them later.

        13. Click Launch.

        Result:

        • Your workload is deployed. This process might take a few minutes to complete.
        • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

        2. Viewing Your Application​

        From the Workloads page, click the link underneath your workload. If your deployment succeeded, your application opens.

        Attention: Cloud-Hosted Sandboxes​

        When using a cloud-hosted virtual machine, you may not have access to the port running the container. In this event, you can test Nginx in an ssh session on the local machine using Execute Shell. Use the port number after the : in the link under your workload if available, which is 31568 in this example.

        gettingstarted@rancher:~$ curl http://localhost:31568
        <!DOCTYPE html>
        <html>
          <head>
            <title>Rancher</title>
            <link rel="icon" href="img/favicon.png">
            <style>
              body {
                background-color: white;
                text-align: center;
                padding: 50px;
                font-family: "Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;
              }
              button {
                  background-color: #0075a8;
                  border: none;
                  color: white;
                  padding: 15px 32px;
                  text-align: center;
                  text-decoration: none;
                  display: inline-block;
                  font-size: 16px;
              }

              #logo {
                margin-bottom: 40px;
              }
            </style>
          </head>
          <body>
            <img id="logo" src="img/rancher-logo.svg" alt="Rancher logo" width=400 />
            <h1>Hello world!</h1>
            <h3>My hostname is hello-world-66b4b9d88b-78bhx</h3>
            <div id='Services'>
              <h3>k8s services found 2</h3>

              <b>INGRESS_D1E1A394F61C108633C4BD37AEDDE757</b> tcp://10.43.203.31:80<br />

              <b>KUBERNETES</b> tcp://10.43.0.1:443<br />

            </div>
            <br />

            <div id='rancherLinks' class="row social">
              <a class="p-a-xs" href="https://rancher.com/docs"><img src="img/favicon.png" alt="Docs" height="25" width="25"></a>
              <a class="p-a-xs" href="https://slack.rancher.io/"><img src="img/icon-slack.svg" alt="slack" height="25" width="25"></a>
              <a class="p-a-xs" href="https://github.com/rancher/rancher"><img src="img/icon-github.svg" alt="github" height="25" width="25"></a>
              <a class="p-a-xs" href="https://twitter.com/Rancher_Labs"><img src="img/icon-twitter.svg" alt="twitter" height="25" width="25"></a>
              <a class="p-a-xs" href="https://www.facebook.com/rancherlabs/"><img src="img/icon-facebook.svg" alt="facebook" height="25" width="25"></a>
              <a class="p-a-xs" href="https://www.linkedin.com/groups/6977008/profile"><img src="img/icon-linkedin.svg" height="25" alt="linkedin" width="25"></a>
            </div>
            <br />
            <button class='button' onclick='myFunction()'>Show request details</button>
            <div id="reqInfo" style='display:none'>
              <h3>Request info</h3>
              <b>Host:</b> 172.22.101.111:31411 <br />
              <b>Pod:</b> hello-world-66b4b9d88b-78bhx </b><br />

              <b>Accept:</b> [*/*]<br />

              <b>User-Agent:</b> [curl/7.47.0]<br />

            </div>
            <br />
            <script>
              function myFunction() {
                  var x = document.getElementById("reqInfo");
                  if (x.style.display === "none") {
                      x.style.display = "block";
                  } else {
                      x.style.display = "none";
                  }
              }
            </script>
          </body>
        </html>
        gettingstarted@rancher:~$

        Finished​

        Congratulations! You have successfully deployed a workload exposed via a NodePort.

        What's Next?​

        When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html b/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html index 9b090273163..6c8b3750bc4 100644 --- a/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html +++ b/v2.0-v2.4/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html @@ -5,13 +5,13 @@ Workload with Ingress Quick Start | Rancher Manager - +
        Version: v2.0-v2.4

        Workload with Ingress Quick Start

        Prerequisite​

        You have a running cluster with at least 1 node.

        1. Deploying a Workload​

        You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

        For this workload, you'll be deploying the application Rancher Hello-World.

        1. From the Clusters page, open the cluster that you just created.

        2. From the main menu of the Dashboard, select Projects/Namespaces.

        3. Open the Project: Default project.

        4. Click Resources > Workloads. In versions before v2.3.0, click Workloads > Workloads.

        5. Click Deploy.

          Step Result: The Deploy Workload page opens.

        6. Enter a Name for your workload.

        7. From the Docker Image field, enter rancher/hello-world. This field is case-sensitive.

        8. Leave the remaining options on their default setting. We'll tell you about them later.

        9. Click Launch.

        Result:

        • Your workload is deployed. This process might take a few minutes to complete.
        • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

        ### 2. Expose The Application Via An Ingress

        Now that the application is up and running it needs to be exposed so that other services can connect.

        1. From the Clusters page, open the cluster that you just created.

        2. From the main menu of the Dashboard, select Projects.

        3. Open the Default project.

        4. Click Resources > Workloads > Load Balancing. In versions before v2.3.0, click the Workloads tab. Click on the Load Balancing tab.

        5. Click Add Ingress.

        6. Enter a name i.e. hello.

        7. In the Target field, drop down the list and choose the name that you set for your service.

        8. Enter 80 in the Port field.

        9. Leave everything else as default and click Save.

        Result: The application is assigned a sslip.io address and exposed. It may take a minute or two to populate.

        View Your Application​

        From the Load Balancing page, click the target link, which will look something like hello.default.xxx.xxx.xxx.xxx.sslip.io > hello-world.

        Your application will open in a separate window.

        Finished​

        Congratulations! You have successfully deployed a workload exposed via an ingress.

        What's Next?​

        When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides.html b/v2.0-v2.4/how-to-guides.html index 608a94482e1..4f4df0da01c 100644 --- a/v2.0-v2.4/how-to-guides.html +++ b/v2.0-v2.4/how-to-guides.html @@ -5,13 +5,13 @@ How-to Guides | Rancher Manager - +
        Version: v2.0-v2.4

        How-to Guides

        How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html index 498d334651d..f53e0ed10a9 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html @@ -5,13 +5,13 @@ Configuring Active Directory (AD) | Rancher Manager - +
        Version: v2.0-v2.4

        Configuring Active Directory (AD)

        If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.

        Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the OpenLDAP authentication integration.

        Note:

        Before you start, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

        Prerequisites​

        You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.

        Usually a (non-admin) Domain User account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.

        Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least Read and List Content permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.

        Using TLS?

        If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

        Configuration Steps​

        Open Active Directory Configuration​

        1. Log into the Rancher UI using the initial local admin account.
        2. From the Global view, navigate to Security > Authentication
        3. Select Active Directory. The Configure an AD server form will be displayed.

        Configure Active Directory Server Settings​

        In the section titled 1. Configure an Active Directory server, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.

        Note:

        If you are unsure about the correct values to enter in the user/group Search Base field, please refer to Identify Search Base and Schema using ldapsearch.

        Table 1: AD Server parameters

        ParameterDescription
        HostnameSpecify the hostname or IP address of the AD server
        PortSpecify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
        TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS).
        Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the AD server unreachable.
        Service Account UsernameEnter the username of an AD account with read-only access to your domain partition (see Prerequisites). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com").
        Service Account PasswordThe password for the service account.
        Default Login DomainWhen you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field must be left empty.
        User Search BaseThe Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
        Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".

        Configure User/Group Schema​

        In the section titled 2. Customize Schema you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.

        Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.

        Note:

        If you are unfamiliar with the schema used in your Active Directory domain, please refer to Identify Search Base and Schema using ldapsearch to determine the correct configuration values.

        User Schema​

        The table below details the parameters for the user schema section configuration.

        Table 2: User schema configuration parameters

        ParameterDescription
        Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
        Username AttributeThe user attribute whose value is suitable as a display name.
        Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to userPrincipalName. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually sAMAccountName.
        User Member AttributeThe attribute containing the groups that a user is a member of.
        Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to userPrincipalName.
        Search FilterThis filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io)). Note: If the search filter does not use valid AD search syntax, the list of users will be empty.
        User Enabled AttributeThe attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard userAccountControl.
        Disabled Status BitmaskThis is the value of the User Enabled Attribute designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see here).

        Group Schema​

        The table below details the parameters for the group schema configuration.

        Table 3: Group schema configuration parameters

        ParameterDescription
        Object ClassThe name of the object class used for group objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
        Name AttributeThe group attribute whose value is suitable for a display name.
        Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
        Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
        Search AttributeAttribute used to construct search filters when adding groups to clusters or projects. See description of user schema Search Attribute.
        Search FilterThis filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use valid AD search syntax, the list of groups will be empty.
        Group DN AttributeThe name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See User Member Attribute.
        Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organisation makes use of these nested memberships (ie. you have groups that contain other groups as members. We advise avoiding nested groups when possible).

        Test Authentication​

        Once you have completed the configuration, proceed by testing the connection to the AD server using your AD admin account. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin.

        Note:

        The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.

        1. Enter the username and password for the AD account that should be mapped to the local principal account.
        2. Click Authenticate with Active Directory to finalise the setup.

        Result:

        • Active Directory authentication has been enabled.
        • You have been signed into Rancher as administrator using the provided AD credentials.

        Note:

        You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

        Annex: Identify Search Base and Schema using ldapsearch​

        In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server.

        The ldapsearch tool allows you to query your AD server to learn about the schema used for user and group objects.

        For the purpose of the example commands provided below we will assume:

        • The Active Directory server has a hostname of ad.acme.com
        • The server is listening for unencrypted connections on port 389
        • The Active Directory domain is acme
        • You have a valid AD account with the username jdoe and password secret

        Identify Search Base​

        First we will use ldapsearch to identify the Distinguished Name (DN) of the parent node(s) for users and groups:

        $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
        -h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"

        This command performs an LDAP search with the search base set to the domain root (-b "dc=acme,dc=com") and a filter targeting the user account (sAMAccountNam=jdoe), returning the attributes for said user:

        Since in this case the user's DN is CN=John Doe,CN=Users,DC=acme,DC=com [5], we should configure the User Search Base with the parent node DN CN=Users,DC=acme,DC=com.

        Similarly, based on the DN of the group referenced in the memberOf attribute [4], the correct value for the Group Search Base would be the parent node of that value, ie. OU=Groups,DC=acme,DC=com.

        Identify User Schema​

        The output of the above ldapsearch query also allows to determine the correct values to use in the user schema configuration:

        • Object Class: person [1]
        • Username Attribute: name [2]
        • Login Attribute: sAMAccountName [3]
        • User Member Attribute: memberOf [4]

        Note:

        If the AD users in our organisation were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the Login Attribute to userPrincipalName instead.

        We'll also set the Search Attribute parameter to sAMAccountName|name. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.

        Identify Group Schema​

        Next, we'll query one of the groups associated with this user, in this case CN=examplegroup,OU=Groups,DC=acme,DC=com:

        $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
        -h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
        -s sub "CN=examplegroup"

        This command will inform us on the attributes used for group objects:

        Again, this allows us to determine the correct values to enter in the group schema configuration:

        • Object Class: group [1]
        • Name Attribute: name [2]
        • Group Member Mapping Attribute: member [3]
        • Search Attribute: sAMAccountName [4]

        Looking at the value of the member attribute, we can see that it contains the DN of the referenced user. This corresponds to the distinguishedName attribute in our user object. Accordingly will have to set the value of the Group Member User Attribute parameter to this attribute.

        In the same way, we can observe that the value in the memberOf attribute in the user object corresponds to the distinguishedName [5] of the group. We therefore need to set the value for the Group DN Attribute parameter to this attribute.

        Annex: Troubleshooting​

        If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html index 0fd96494b57..cc0072edf9a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html @@ -5,13 +5,13 @@ Configuring Azure AD | Rancher Manager - +
        Version: v2.0-v2.4

        Configuring Azure AD

        Available as of v2.0.3

        If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.

        Note: Azure AD integration only supports Service Provider initiated logins.

        Prerequisite: Have an instance of Azure AD configured.

        Note: Most of this procedure takes place from the Microsoft Azure Portal.

        Azure Active Directory Configuration Outline​

        Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.

        Tip: Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.

        1. Register Rancher with Azure​

        Before enabling Azure AD within Rancher, you must register Rancher with Azure.

        1. Log in to Microsoft Azure as an administrative user. Configuration in future steps requires administrative access rights.

        2. Use search to open the App registrations service.

          Open App Registrations

        3. Click New registrations and complete the Create form.

          New App Registration

          1. Enter a Name (something like Rancher).

          2. From Supported account types, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.

          3. In the Redirect URI section, make sure Web is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: <MY_RANCHER_URL>/verify-auth-azure.

            Tip: You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).

          4. Click Register.

        Note: It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.

        2. Create a new client secret​

        From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.

        1. Use search to open App registrations services. Then open the entry for Rancher that you created in the last procedure.

          Open Rancher Registration

        2. From the navigation pane on left, click Certificates and Secrets.

        3. Click New client secret.

          ![Create new client secret](/img/select-client-secret.png)

          1. Enter a **Description** (something like `Rancher`).

          1. Select duration for the key from the options under **Expires**. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.

          1. Click **Add** (you don't need to enter a value—it will automatically populate after you save).

        4. Copy the key value and save it to an empty text file.

          You'll enter this key into the Rancher UI later as your Application Secret.

          You won't be able to access the key value again within the Azure UI.

        3. Set Required Permissions for Rancher​

        Next, set API permissions for Rancher within Azure.

        1. From the navigation pane on left, select API permissions.

          Open Required Permissions

        2. Click Add a permission.

        3. From the Azure Active Directory Graph, select the following Delegated Permissions:

          Select API Permissions



          - **Access the directory as the signed-in user** - **Read directory data** - **Read all groups** - **Read all users' full profiles** - **Read all users' basic profiles** - **Sign in and read user profile**

        4. Click Add permissions.

        5. From API permissions, click Grant admin consent. Then click Yes.

          Note: You must be signed in as an Azure administrator to successfully save your permission settings.

        4. Add a Reply URL​

        To use Azure AD with Rancher you must whitelist Rancher with Azure. You can complete this whitelisting by providing Azure with a reply URL for Rancher, which is your Rancher Server URL followed with a verification path.

        1. From the Setting blade, select Reply URLs.

          Azure: Enter Reply URL

        2. From the Reply URLs blade, enter the URL of your Rancher Server, appended with the verification path: <MY_RANCHER_URL>/verify-auth-azure.

          Tip: You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).

        3. Click Save.

        Result: Your reply URL is saved.

        Note: It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.

        5. Copy Azure Application Data​

        As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.

        1. Obtain your Rancher Tenant ID.

          1. Use search to open the Azure Active Directory service.

            Open Azure Active Directory

          2. From the left navigation pane, open Overview.

          3. Copy the Directory ID and paste it into your text file.

            You'll paste this value into Rancher as your Tenant ID.

        2. Obtain your Rancher Application ID.

          1. Use search to open App registrations.

            Open App Registrations

          2. Find the entry you created for Rancher.

          3. Copy the Application ID and paste it to your text file.

        3. Obtain your Rancher Graph Endpoint, Token Endpoint, and Auth Endpoint.

          1. From App registrations, click Endpoints.

            Click Endpoints

          2. Copy the following endpoints to your clipboard and paste them into your text file (these values will be your Rancher endpoint values).

            • Microsoft Graph API endpoint (Graph Endpoint)
            • OAuth 2.0 token endpoint (v1) (Token Endpoint)
            • OAuth 2.0 authorization endpoint (v1) (Auth Endpoint)

        Note: Copy the v1 version of the endpoints

        6. Configure Azure AD in Rancher​

        From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.

        Enter the values that you copied to your text file.

        1. Log into Rancher. From the Global view, select Security > Authentication.

        2. Select Azure AD.

        3. Complete the Configure Azure AD Account form using the information you copied while completing Copy Azure Application Data.

          Important: When entering your Graph Endpoint, remove the tenant ID from the URL, like below.

          https://graph.windows.net/abb5adde-bee8-4821-8b03-e63efdc7701c

          The following table maps the values you copied in the Azure portal to the fields in Rancher.

          Rancher FieldAzure Value
          Tenant IDDirectory ID
          Application IDApplication ID
          Application SecretKey Value
          Endpointhttps://login.microsoftonline.com/
          Graph EndpointMicrosoft Azure AD Graph API Endpoint
          Token EndpointOAuth 2.0 Token Endpoint
          Auth EndpointOAuth 2.0 Authorization Endpoint

        4. Click Authenticate with Azure.

        Result: Azure Active Directory authentication is configured.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html index 30d30db5388..500ec57d0e2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html @@ -5,14 +5,14 @@ Configuring FreeIPA | Rancher Manager - +
        Version: v2.0-v2.4

        Configuring FreeIPA

        Available as of v2.0.5

        If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.

        Prerequisites:

        1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

        2. From the Global view, select Security > Authentication from the main menu.

        3. Select FreeIPA.

        4. Complete the Configure an FreeIPA server form.

          You may need to log in to your domain controller to find the information requested in the form.

          Using TLS? If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.



          **User Search Base vs. Group Search Base**

          Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.

          • If your users and groups are in the same search base, complete only the User Search Base.
          • If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.

        5. If your FreeIPA deviates from the standard AD schema, complete the Customize Schema form to match it. Otherwise, skip this step.

          Search Attribute The Search Attribute field defaults with three specific values: uid|sn|givenName. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.

          The default field value uid|sn|givenName, but you can configure this field to a subset of these fields. The pipe (|) between the fields separates these fields.

          • uid: User ID
          • sn: Last Name
          • givenName: First Name

          With this search attribute, Rancher creates search filters for users and groups, but you cannot add your own search filters in this field.

        6. Enter your FreeIPA username and password in Authenticate with FreeIPA to confirm that Rancher is configured to use FreeIPA authentication.

        Result:

        • FreeIPA authentication is configured.
        • You are signed into Rancher with your FreeIPA account (i.e., the external principal).
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html index a87522992bd..f50cdd875f2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html @@ -5,13 +5,13 @@ Configuring GitHub | Rancher Manager - +
        Version: v2.0-v2.4

        Configuring GitHub

        In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.

        Prerequisites: Read External Authentication Configuration and Principal Users.

        1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

        2. From the Global view, select Security > Authentication from the main menu.

        3. Select GitHub.

        4. Follow the directions displayed to Setup a GitHub Application. Rancher redirects you to GitHub to complete registration.

          What's an Authorization Callback URL?

          The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).

          When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.

        5. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.

          Where do I find the Client ID and Client Secret?

          From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.

        6. Click Authenticate with GitHub.

        7. Use the Site Access options to configure the scope of user authorization.

          • Allow any valid Users

            Any GitHub user can access Rancher. We generally discourage use of this setting!

          • Allow members of Clusters, Projects, plus Authorized Users and Organizations

            Any GitHub user or group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any GitHub user or group you add to the Authorized Users and Organizations list may log in to Rancher.

          • Restrict access to only Authorized Users and Organizations

            Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.


        8. Click Save.

        Result:

        • GitHub authentication is configured.
        • You are signed into Rancher with your GitHub account (i.e., the external principal).
        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html index 515afd2f3b7..2b03d16257a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html @@ -5,7 +5,7 @@ Configuring Google OAuth | Rancher Manager - + @@ -13,7 +13,7 @@
        Version: v2.0-v2.4

        Configuring Google OAuth

        Available as of v2.3.0

        If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials.

        Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher.

        Within Rancher, only administrators or users with the Manage Authentication global role can configure authentication.

        Prerequisites

        • You must have a G Suite admin account configured.
        • G Suite requires a top private domain FQDN as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL.
        • You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on this page.

        After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: Enable Admin APIs

        Setting up G Suite for OAuth with Rancher

        Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following:

        1. Add Rancher as an authorized domain in G Suite
        2. Generate OAuth2 credentials for the Rancher server
        3. Create service account credentials for the Rancher server
        4. Register the service account key as an OAuth Client

        1. Adding Rancher as an Authorized Domain​

        1. Click here to go to credentials page of your Google domain.
        2. Select your project and click OAuth consent screen.OAuth Consent Screen
        3. Go to Authorized Domains and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to this article.
        4. Go to Scopes for Google APIs and make sure email, profile and openid are enabled.

        Result: Rancher has been added as an authorized domain for the Admin SDK API.

        2. Creating OAuth2 Credentials for the Rancher Server​

        1. Go to the Google API console, select your project, and go to the credentials page.Credentials
        2. On the Create Credentials dropdown, select OAuth client ID.
        3. Click Web application.
        4. Provide a name.
        5. Fill out the Authorized JavaScript origins and Authorized redirect URIs. Note: The Rancher UI page for setting up Google OAuth (available from the Global view under Security > Authentication > Google) provides you the exact links to enter for this step.
        • Under Authorized JavaScript origins, enter your Rancher server URL.
        • Under Authorized redirect URIs, enter your Rancher server URL appended with the path verify-auth. For example, if your URI is https://rancherServer, you will enter https://rancherServer/verify-auth.
        1. Click on Create.
        2. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click Download JSON. Save the file so that you can provide these credentials to Rancher.

        Result: Your OAuth credentials have been successfully created.

        3. Creating Service Account Credentials​

        Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups.

        Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed.

        As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account.

        This section describes how to:

        • Create a service account
        • Create a key for the service account and download the credentials as JSON
        1. Click here and select your project for which you generated OAuth credentials.
        2. Click on Create Service Account.
        3. Enter a name and click Create.Service account creation Step 1
        4. Don't provide any roles on the Service account permissions page and click ContinueService account creation Step 2
        5. Click on Create Key and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher. Service account creation Step 3

        Result: Your service account is created.

        4. Register the Service Account Key as an OAuth Client​

        You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups.

        Using the Unique ID of the service account key, register it as an Oauth Client using the following steps:

        1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click Unique ID and click OK. This will add a Unique ID column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field Key ID.

          Service account Unique ID

        2. Go to the Manage OAuth Client Access page.

        3. Add the Unique ID obtained in the previous step in the Client Name field.

        4. In the One or More API Scopes field, add the following scopes:

          openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly

        5. Click Authorize.

        Result: The service account is registered as an OAuth client in your G Suite account.

        Configuring Google OAuth in Rancher

        1. Sign into Rancher using a local user assigned the administrator role. This user is also called the local principal.
        2. From the Global view, click Security > Authentication from the main menu.
        3. Click Google. The instructions in the UI cover the steps to set up authentication with Google OAuth.
          1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
          2. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
          3. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
          • Step One is about adding Rancher as an authorized domain, which we already covered in this section.
          • For Step Two, provide the OAuth credentials JSON that you downloaded after completing this section. You can upload the file or paste the contents into the OAuth Credentials field.
          • For Step Three, provide the service account credentials JSON that downloaded at the end of this section. The credentials will only work if you successfully registered the service account key as an OAuth client in your G Suite account.
        4. Click Authenticate with Google.
        5. Click Save.

        Result: Google authentication is successfully configured.

        Copyright © 2022 SUSE Rancher. All Rights Reserved.
        - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html index 8995d73da6a..3301575a60c 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html @@ -5,7 +5,7 @@ Configuring Keycloak (SAML) | Rancher Manager - + @@ -17,7 +17,7 @@ From the Installation tab, choose the SAML Metadata IDPSSODes Keycloak versions 6.0.0 and up no longer provide the IDP metadata under the Installation tab. You can still get the XML from the following url:

        https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}/protocol/saml/descriptor

        The XML obtained from this URL contains EntitiesDescriptor as the root element. Rancher expects the root element to be EntityDescriptor rather than EntitiesDescriptor. So before passing this XML to Rancher, follow these steps to adjust it:

        • Copy all the attributes from EntitiesDescriptor to the EntityDescriptor that are not present.
        • Remove the <EntitiesDescriptor> tag from the beginning.
        • Remove the </EntitiesDescriptor> from the end of the xml.

        You are left with something similar as the example below:

        <EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
          ....
        </EntityDescriptor>

      Configuring Keycloak in Rancher​

      1. From the Global view, select Security > Authentication from the main menu.

      2. Select Keycloak.

      3. Complete the Configure Keycloak Account form.

      | Field                     | Description                                                                                                                                              |
      | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | Display Name Field        | The attribute that contains the display name of users. <br/><br/>Example: `givenName`                                                                    |
      | User Name Field           | The attribute that contains the user name/given name. <br/><br/>Example: `email`                                                                         |
      | UID Field                 | An attribute that is unique to every user. <br/><br/>Example: `email`                                                                                    |
      | Groups Field              | Make entries for managing group memberships. <br/><br/>Example: `member`                                                                                 |
      | Entity ID Field           | The ID that needs to be configured as a client ID in the Keycloak client. <br/><br/>Default: `https://yourRancherHostURL/v1-saml/keycloak/saml/metadata` |
      | Rancher API Host          | The URL for your Rancher Server.                                                                                                                         |
      | Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP.                                                                            |
      | IDP-metadata              | The `metadata.xml` file that you exported from your IdP server.                                                                                          |

      >**Tip:** You can generate a key/certificate pair using an openssl command. For example:
      >
      >        openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

      1. After you complete the Configure Keycloak Account form, click Authenticate with Keycloak, which is at the bottom of the page.

        Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

        Note: You may have to disable your popup blocker to see the IdP login page.

      Result: Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.

      SAML Provider Caveats:
      • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
      • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
      • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
      • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

      Annex: Troubleshooting​

      If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

      You are not redirected to Keycloak​

      When you click on Authenticate with Keycloak, your are not redirected to your IdP.

      • Verify your Keycloak client configuration.
      • Make sure Force Post Binding set to OFF.

      Forbidden message displayed after IdP login​

      You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a Forbidden message afterwards.

      • Check the Rancher debug log.
      • If the log displays ERROR: either the Response or Assertion must be signed, make sure either Sign Documents or Sign assertions is set to ON in your Keycloak client.

      HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata​

      This is usually due to the metadata not being created until a SAML provider is configured. Try configuring and saving keycloak as your SAML provider and then accessing the metadata.

      Keycloak Error: "We're sorry, failed to process response"​

      • Check your Keycloak log.
      • If the log displays failed: org.keycloak.common.VerificationException: Client does not have a public key, set Encrypt Assertions to OFF in your Keycloak client.

      Keycloak Error: "We're sorry, invalid requester"​

      • Check your Keycloak log.
      • If the log displays request validation failed: org.keycloak.common.VerificationException: SigAlg was null, set Client Signature Required to OFF in your Keycloak client.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html index 15633f571d2..5e88ec8b4d1 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html @@ -5,13 +5,13 @@ Configuring Okta (SAML) | Rancher Manager - +
      Version: v2.0-v2.4

      Configuring Okta (SAML)

      Available as of v2.2.0

      If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

      Note: Okta integration only supports Service Provider initiated logins.

      Prerequisites​

      In Okta, create a SAML Application with the settings below. See the Okta documentation for help.

      SettingValue
      Single Sign on URLhttps://yourRancherHostURL/v1-saml/okta/saml/acs
      Audience URI (SP Entity ID)https://yourRancherHostURL/v1-saml/okta/saml/metadata

      Configuring Okta in Rancher​

      1. From the Global view, select Security > Authentication from the main menu.

      2. Select Okta.

      3. Complete the Configure Okta Account form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.

        FieldDescription
        Display Name FieldThe attribute name from an attribute statement that contains the display name of users.
        User Name FieldThe attribute name from an attribute statement that contains the user name/given name.
        UID FieldThe attribute name from an attribute statement that is unique to every user.
        Groups FieldThe attribute name in a group attribute statement that exposes your groups.
        Rancher API HostThe URL for your Rancher Server.
        Private Key / CertificateA key/certificate pair used for Assertion Encryption.
        Metadata XMLThe Identity Provider metadata file that you find in the application Sign On section.

        Tip: You can generate a key/certificate pair using an openssl command. For example:

           openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt

      1. After you complete the Configure Okta Account form, click Authenticate with Okta, which is at the bottom of the page.

        Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.

        Note: If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.

      Result: Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.

      SAML Provider Caveats:
      • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
      • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
      • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
      • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html index 968a863ba06..c502fc66496 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html @@ -5,7 +5,7 @@ Configuring PingIdentity (SAML) | Rancher Manager - + @@ -14,7 +14,7 @@ Metadata URL: https://<rancher-server>/v1-saml/ping/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/ping/saml/acs Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
    • Export a metadata.xml file from your IdP Server. For more information, see the PingIdentity documentation.

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select PingIdentity.

    3. Complete the Configure Ping Account form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Entity ID Field (optional): The published, protocol-dependent, unique identifier of your partner. This ID defines your organization as the entity operating the server for SAML 2.0 transactions. This ID may have been obtained out-of-band or via a SAML metadata file.

      6. Rancher API Host: Enter the URL for your Rancher Server.

      7. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      8. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Ping Account form, click Authenticate with Ping, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.

      Note: You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html index 1e500c8760b..4ac3f997089 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html @@ -5,13 +5,13 @@ Local Authentication | Rancher Manager - +
    Version: v2.0-v2.4

    Local Authentication

    Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the admin user that logs in to Rancher for the first time is a local user.

    Adding Local Users​

    Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.

    1. From the Global view, select Users from the navigation bar.

    2. Click Add User. Then complete the Add User form. Click Create when you're done.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html index eb7493dc1eb..b1fbc107e7a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html @@ -5,13 +5,13 @@ Users and Groups | Rancher Manager - +
    Version: v2.0-v2.4

    Users and Groups

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.

    Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see Role Based Access Control.

    Managing Members​

    When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a local user account, you will not be able to search for GitHub users or groups.

    All users, whether they are local users or from an authentication provider, can be viewed and managed. From the Global view, click on Users.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    User Information​

    Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.

    Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.

    Automatically Refreshing User Information​

    Available as of v2.2.0

    Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh. From the Global view, click on Settings. Two settings control this behavior:

    • auth-user-info-max-age-seconds

      This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to 3600 seconds, i.e. 1 hour.

    • auth-user-info-resync-cron

      This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to 0 0 * * *, i.e. once a day at midnight. See the Cron documentation for more information on valid values for this setting.

    Note: Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.

    Manually Refreshing User Information​

    If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.

    1. From the Global view, click on Users in the navigation bar.

    2. Click on Refresh Group Memberships.

    Results: Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.

    Note: Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.

    Session Length​

    Available as of v2.3.0

    The default length (TTL) of each user session is adjustable. The default session length is 16 hours.

    1. From the Global view, click on Settings.
    2. In the Settings page, find auth-user-session-ttl-minutes and click Edit.
    3. Enter the amount of time in minutes a session length should last and click Save.

    Result: Users are automatically logged out of Rancher after the set number of minutes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html index 8bff5a7a7e9..db303d19eab 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html @@ -5,14 +5,14 @@ 1. Configuring Microsoft AD FS for Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    1. Configuring Microsoft AD FS for Rancher

    Before configuring Rancher to support AD FS users, you must add Rancher as a relying party trust in AD FS.

    1. Log into your AD server as an administrative user.

    2. Open the AD FS Management console. Select Add Relying Party Trust... from the Actions menu and click Start.

    3. Select Enter data about the relying party manually as the option for obtaining data about the relying party.

    4. Enter your desired Display name for your Relying Party Trust. For example, Rancher.

    5. Select AD FS profile as the configuration profile for your relying party trust.

    6. Leave the optional token encryption certificate empty, as Rancher AD FS will not be using one.

    7. Select Enable support for the SAML 2.0 WebSSO protocol and enter https://<rancher-server>/v1-saml/adfs/saml/acs for the service URL.

    8. Add https://<rancher-server>/v1-saml/adfs/saml/metadata as the Relying party trust identifier.

    9. This tutorial will not cover multi-factor authentication; please refer to the Microsoft documentation if you would like to configure multi-factor authentication.

    10. From Choose Issuance Authorization RUles, you may select either of the options available according to use case. However, for the purposes of this guide, select Permit all users to access this relying party.

    11. After reviewing your settings, select Next to add the relying party trust.

    1. Select Open the Edit Claim Rules... and click Close.

    2. On the Issuance Transform Rules tab, click Add Rule....

    3. Select Send LDAP Attributes as Claims as the Claim rule template.

    4. Set the Claim rule name to your desired name (for example, Rancher Attributes) and select Active Directory as the Attribute store. Create the following mapping to reflect the table below:

      LDAP AttributeOutgoing Claim Type
      Given-NameGiven Name
      User-Principal-NameUPN
      Token-Groups - Qualified by Long Domain NameGroup
      SAM-Account-NameName

      ![](/img/adfs/adfs-add-tcr-2.png)

    5. Download the federationmetadata.xml from your AD server at:

    https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    Result: You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.

    Next: Configuring Rancher for Microsoft AD FS​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html index 3206f4eb783..76089df0e52 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html @@ -5,13 +5,13 @@ 2. Configuring Rancher for Microsoft AD FS | Rancher Manager - +
    Version: v2.0-v2.4

    2. Configuring Rancher for Microsoft AD FS

    Available as of v2.0.7

    After you complete Configuring Microsoft AD FS for Rancher, enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.

    Important Notes For Configuring Your AD FS Server:

    • The SAML 2.0 WebSSO Protocol Service URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs
    • The Relying Party Trust identifier URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata
    • You must export the federationmetadata.xml file from your AD FS server. This can be found at: https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Microsoft Active Directory Federation Services.

    3. Complete the Configure AD FS Account form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The configuration section below describe how you can map AD attributes to fields within Rancher.

    1. After you complete the Configure AD FS Account form, click Authenticate with AD FS, which is at the bottom of the page.

      Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.

      Note: You may have to disable your popup blocker to see the AD FS login page.

    Result: Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.

    Configuration

    FieldDescription
    Display Name FieldThe AD attribute that contains the display name of users.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    User Name FieldThe AD attribute that contains the user name/given name.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    UID FieldAn AD attribute that is unique to every user.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
    Groups FieldMake entries for managing group memberships.

    Example: http://schemas.xmlsoap.org/claims/Group
    Rancher API HostThe URL for your Rancher Server.
    Private Key / CertificateThis is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.

    Certificate creation command
    Metadata XMLThe federationmetadata.xml file exported from your AD FS server.

    You can find this file at https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml.

    Tip: You can generate a certificate using an openssl command. For example:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html index 158dc0e790f..26b507e5684 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html @@ -5,13 +5,13 @@ Group Permissions with Shibboleth and OpenLDAP | Rancher Manager - +
    Version: v2.0-v2.4

    Group Permissions with Shibboleth and OpenLDAP

    Available as of Rancher v2.4

    This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.

    Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.

    One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.

    Terminology​

    • Shibboleth is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
    • SAML: Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
    • OpenLDAP: a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
    • IdP or IDP: An identity provider. OpenLDAP is an example of an identity provider.

    Adding OpenLDAP Group Permissions to Rancher Resources​

    The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.

    For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.

    In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.

    When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.

    Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.

    Adding OpenLDAP Group Permissions to Rancher Resources

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html index 81144d52ed0..fc58c47ad4e 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html @@ -5,13 +5,13 @@ Cluster Drivers | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Drivers

    Available as of v2.2.0

    Cluster drivers are used to create clusters in a hosted Kubernetes provider, such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.

    If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.

    Managing Cluster Drivers​

    Prerequisites: To create, edit, or delete cluster drivers, you need one of the following permissions:

    Activating/Deactivating Cluster Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.

    1. From the Global view, choose Tools > Drivers in the navigation bar.

    2. From the Drivers page, select the Cluster Drivers tab.

    3. Select the driver that you wish to Activate or Deactivate and select the appropriate icon.

    Adding Custom Cluster Drivers​

    If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create hosted kubernetes clusters.

    1. From the Global view, choose Tools > Drivers in the navigation bar.

    2. From the Drivers page select the Cluster Drivers tab.

    3. Click Add Cluster Driver.

    4. Complete the Add Cluster Driver form. Then click Create.

    Developing your own Cluster Driver​

    In order to develop cluster driver to add to Rancher, please refer to our example.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html index ac1fecce7f3..94cc08b7087 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html @@ -5,13 +5,13 @@ Node Drivers | Rancher Manager - +
    Version: v2.0-v2.4

    Node Drivers

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Managing Node Drivers​

    Prerequisites: To create, edit, or delete drivers, you need one of the following permissions:

    Activating/Deactivating Node Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.

    1. From the Global view, choose Tools > Drivers in the navigation bar. From the Drivers page, select the Node Drivers tab. In version before v2.2.0, you can select Node Drivers directly in the navigation bar.

    2. Select the driver that you wish to Activate or Deactivate and select the appropriate icon.

    Adding Custom Node Drivers​

    If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.

    1. From the Global view, choose Tools > Drivers in the navigation bar. From the Drivers page, select the Node Drivers tab. In version before v2.2.0, you can select Node Drivers directly in the navigation bar.

    2. Click Add Node Driver.

    3. Complete the Add Node Driver form. Then click Create.

    Developing your own node driver​

    Node drivers are implemented with Docker Machine.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html index 621aad798a5..93f546295f1 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html @@ -5,13 +5,13 @@ Access and Sharing | Rancher Manager - +
    Version: v2.0-v2.4

    Access and Sharing

    If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.

    Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.

    When you share a template, each user can have one of two access levels:

    • Owner: This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
    • User: These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as Make Public (read-only), all users in your Rancher setup have the User access level for the template.

    If you create a template, you automatically become an owner of that template.

    If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the documentation about revising templates.

    There are several ways to share templates:

    • Add users to a new RKE template during template creation
    • Add users to an existing RKE template
    • Make the RKE template public, sharing it with all users in the Rancher setup
    • Share template ownership with users who are trusted to modify the template

    Sharing Templates with Specific Users or Groups​

    To allow users or groups to create clusters using your template, you can give them the basic User access level for the template.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to share and click the ⋮ > Edit.
    3. In the Share Template section, click on Add Member.
    4. Search in the Name field for the user or group you want to share the template with.
    5. Choose the User access type.
    6. Click Save.

    Result: The user or group can create clusters using the template.

    Sharing Templates with All Users​

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to share and click the ⋮ > Edit.
    3. Under Share Template, click Make Public (read-only). Then click Save.

    Result: All users in the Rancher setup can create clusters using the template.

    Sharing Ownership of Templates​

    If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.

    In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.

    To give Owner access to a user or group,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to share and click the ⋮ > Edit.
    3. Under Share Template, click on Add Member and search in the Name field for the user or group you want to share the template with.
    4. In the Access Type field, click Owner.
    5. Click Save.

    Result: The user or group has the Owner access type, and can modify, share, or delete the template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html index 656777a0af6..619f7058095 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html @@ -5,13 +5,13 @@ Applying Templates | Rancher Manager - +
    Version: v2.0-v2.4

    Applying Templates

    You can create a cluster from an RKE template that you created, or from a template that has been shared with you.

    RKE templates can be applied to new clusters.

    As of Rancher v2.3.3, you can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Creating a Cluster from an RKE Template​

    To add a cluster hosted by an infrastructure provider using an RKE template, use these steps:

    1. From the Global view, go to the Clusters tab.
    2. Click Add Cluster and choose the infrastructure provider.
    3. Provide the cluster name and node template details as usual.
    4. To use an RKE template, under the Cluster Options, check the box for Use an existing RKE template and revision.
    5. Choose an existing template and revision from the dropdown menu.
    6. Optional: You can edit any settings that the RKE template owner marked as Allow User Override when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
    7. Click Save to launch the cluster.

    Updating a Cluster Created with an RKE Template​

    When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.

    • If the setting allows a user override, you can update these settings in the cluster by editing the cluster.
    • If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.

    If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.

    As of Rancher v2.3.3, an existing cluster's settings can be saved as an RKE template. In that situation, you can also edit the cluster to update the cluster to a new revision of the template.

    Note: You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Converting an Existing Cluster to Use an RKE Template​

    Available as of v2.3.3

    This section describes how to create an RKE template from an existing cluster.

    RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to use a newer version of the template.

    To convert an existing cluster to use an RKE template,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that will be converted to use an RKE template. Click ⋮ > Save as RKE Template.
    3. Enter a name for the template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html index 37e2a9e65da..d6b4608dcc0 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html @@ -5,13 +5,13 @@ Template Creator Permissions | Rancher Manager - +
    Version: v2.0-v2.4

    Template Creator Permissions

    Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.

    For more information on administrator permissions, refer to the documentation on global permissions.

    Giving Users Permission to Create Templates

    Templates can only be created by users who have the global permission Create RKE Templates.

    Administrators have the global permission to create templates, and only administrators can give that permission to other users.

    For information on allowing users to modify existing templates, refer to Sharing Templates.

    Administrators can give users permission to create RKE templates in two ways:

    Allowing a User to Create Templates​

    An administrator can individually grant the role Create RKE Templates to any existing user by following these steps:

    1. From the global view, click the Users tab. Choose the user you want to edit and click the ⋮ > Edit.
    2. In the Global Permissions section, choose Custom and select the Create RKE Templates role along with any other roles the user should have. Click Save.

    Result: The user has permission to create RKE templates.

    Allowing New Users to Create Templates by Default​

    Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.

    1. From the Global view, click Security > Roles.
    2. Under the Global roles tab, go to the role Create RKE Templates and click the ⋮ > Edit.
    3. Select the option Yes: Default role for new users and click Save.

    Result: Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.

    Revoking Permission to Create Templates​

    Administrators can remove a user's permission to create templates with the following steps:

    1. From the global view, click the Users tab. Choose the user you want to edit and click the ⋮ > Edit.
    2. In the Global Permissions section, un-check the box for Create RKE Templates. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions.
    3. Click Save.

    Result: The user cannot create RKE templates.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html index 301b54bac85..d55a7e5f0b9 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html @@ -5,13 +5,13 @@ Template Enforcement | Rancher Manager - +
    Version: v2.0-v2.4

    Template Enforcement

    This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.

    By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,

    • Only an administrator has the ability to create clusters without a template.
    • All standard users must use an RKE template to create a new cluster.
    • Standard users cannot create a cluster without using a template.

    Users can only create new templates if the administrator gives them permission.

    After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to upgrade the cluster to a new revision of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the documentation on revising templates.

    Requiring New Clusters to Use an RKE Template​

    You might want to require new clusters to use a template to ensure that any cluster launched by a standard user will use the Kubernetes and/or Rancher settings that are vetted by administrators.

    To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:

    1. From the Global view, click the Settings tab.
    2. Go to the cluster-template-enforcement setting. Click the vertical ⋮ and click Edit.
    3. Set the value to True and click Save.

    Result: All clusters provisioned by Rancher must use a template, unless the creator is an administrator.

    Disabling RKE Template Enforcement​

    To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:

    1. From the Global view, click the Settings tab.
    2. Go to the cluster-template-enforcement setting. Click the vertical ⋮ and click Edit.
    3. Set the value to False and click Save.

    Result: When clusters are provisioned by Rancher, they don't need to use a template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html index 74fb40dfc61..550ccb4e7ee 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html @@ -5,13 +5,13 @@ Example Scenarios | Rancher Manager - +
    Version: v2.0-v2.4

    Example Scenarios

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    • Enforcing templates: Administrators might want to enforce one or more template settings for everyone if they want all new Rancher-provisioned clusters to have those settings.
    • Sharing different templates with different users: Administrators might give different templates to basic and advanced users, so that basic users have more restricted options and advanced users have more discretion when creating clusters.
    • Updating template settings: If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, a template can be updated to a new revision and clusters created from the template can upgrade to the new version of the template.
    • Sharing ownership of a template: When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how template ownership can be shared.

    Enforcing a Template Setting for Everyone​

    Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.

    1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as Allow User Override.
    2. The administrator makes the template public.
    3. The administrator turns on template enforcement.

    Results:

    • All Rancher users in the organization have access to the template.
    • All new clusters created by standard users with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them.
    • All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template.

    In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else.

    Templates for Basic and Advanced Users​

    Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want.

    1. First, an administrator turns on RKE template enforcement. This means that every standard user in Rancher will need to use an RKE template when they create a cluster.
    2. The administrator then creates two templates:
    • One template for basic users, with almost every option specified except for access keys
    • One template for advanced users, which has most or all options has Allow User Override turned on
    1. The administrator shares the advanced template with only the advanced users.
    2. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster.

    Result: All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters.

    Updating Templates and Clusters Created with Them​

    Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes.

    In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting.

    The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters:

    • Specify Kubernetes v1.15 on the template: The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster.
    • Allow any Kubernetes version on the template: When creating a template revision, the template owner can also mark the the Kubernetes version as Allow User Override using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes.
    • Allow the latest minor Kubernetes version on the template: The template owner can also create a template revision in which the Kubernetes version is defined as Latest v1.14 (Allows patch version upgrades). This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed.

    Allowing Other Users to Control and Share a Template​

    Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster.

    Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template.

    To share ownership of the template with Bob, Alice adds Bob as an owner of her template.

    The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html index ea540082d74..5633de041ce 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html @@ -5,13 +5,13 @@ RKE Templates and Infrastructure | Rancher Manager - +
    Version: v2.0-v2.4

    RKE Templates and Infrastructure

    In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.

    Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.

    If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.

    Node Templates​

    Node templates are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.

    Terraform​

    Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.

    This section focuses on how to use Terraform with the Rancher 2 Terraform provider, which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.

    Terraform allows you to:

    • Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
    • Leverage catalog apps and multi-cluster apps
    • Codify infrastructure across many platforms, including Rancher and major cloud providers
    • Commit infrastructure-as-code to version control
    • Easily repeat configuration and setup of infrastructure
    • Incorporate infrastructure changes into standard development practices
    • Prevent configuration drift, in which some servers become configured differently than others

    How Does Terraform Work?​

    Terraform is written in files with the extension .tf. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.

    To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with.

    Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.

    When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run terraform apply, the changes would be deployed.

    Tips for Working with Terraform​

    • There are examples of how to provide most aspects of a cluster in the documentation for the Rancher 2 provider.

    • In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver.

    • You can also modify auth in the Terraform provider.

    • You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure.

    • If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use Terraform modules. You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware.

    Tip for Creating CIS Benchmark Compliant Clusters​

    This section describes one way that you can make security and compliance-related config files standard in your clusters.

    When you create a CIS benchmark compliant cluster, you have an encryption config file and an audit log config file.

    Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the kube-api-server.

    Then you would make sure that the kube-api-server flag in your RKE template uses your CIS-compliant config files.

    In this way, you can create flags that comply with the CIS benchmark.

    Resources​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html index 11217b3896c..c8a8c67721f 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html @@ -5,14 +5,14 @@ Creating and Revising Templates | Rancher Manager - +
    Version: v2.0-v2.4

    Creating and Revising Templates

    This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the Global view under Tools > RKE Templates.

    Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.

    Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.

    The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.

    Prerequisites​

    You can create RKE templates if you have the Create RKE Templates permission, which can be given by an administrator.

    You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to the documentation on sharing template ownership.

    Creating a Template​

    1. From the Global view, click Tools > RKE Templates.
    2. Click Add Template.
    3. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
    4. Optional: Share the template with other users or groups by adding them as members. You can also make the template public to share with everyone in the Rancher setup.
    5. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.

    Result: An RKE template with one revision is configured. You can use this RKE template revision later when you provision a Rancher-launched cluster. After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck Use an existing RKE Template and Revision will be unavailable.

    Updating a Template​

    When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.

    You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can disable it.

    When new template revisions are created, clusters using an older revision of the template are unaffected.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to edit and click the ⋮ > Edit.
    3. Edit the required information and click Save.
    4. Optional: You can change the default revision of this template and also change who it is shared with.

    Result: The template is updated. To apply it to a cluster using an older version of the template, refer to the section on upgrading a cluster to use a new revision of a template.

    Deleting a Template​

    When you no longer use an RKE template for any of your clusters, you can delete it.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to delete and click the ⋮ > Delete.
    3. Confirm the deletion when prompted.

    Result: The template is deleted.

    Creating a Revision Based on the Default Revision​

    You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to clone and click the ⋮ > New Revision From Default.
    3. Complete the rest of the form to create a new revision.

    Result: The RKE template revision is cloned and configured.

    Creating a Revision Based on a Cloned Revision​

    When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to clone. Then select ⋮ > Clone Revision.
    3. Complete the rest of the form.

    Result: The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.

    Disabling a Template Revision​

    When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.

    You can disable the revision if it is not being used by any cluster.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to disable. Then select ⋮ > Disable.

    Result: The RKE template revision cannot be used to create a new cluster.

    Re-enabling a Disabled Template Revision​

    If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to re-enable. Then select ⋮ > Enable.

    Result: The RKE template revision can be used to create a new cluster.

    Setting a Template Revision as Default​

    When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.

    To set an RKE template revision as default,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template revision that should be default and click the ⋮ > Set as Default.

    Result: The RKE template revision will be used as the default option when clusters are created with the template.

    Deleting a Template Revision​

    You can delete all revisions of a template except for the default revision.

    To permanently delete a revision,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template revision that should be deleted and click the ⋮ > Delete.

    Result: The RKE template revision is deleted.

    Upgrading a Cluster to Use a New Template Revision​

    This section assumes that you already have a cluster that has an RKE template applied. This section also assumes that you have updated the template that the cluster is using so that a new template revision is available.

    To upgrade a cluster to use a new template revision,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that you want to upgrade and click ⋮ > Edit.
    3. In the Cluster Options section, click the dropdown menu for the template revision, then select the new template revision.
    4. Click Save.

    Result: The cluster is upgraded to use the settings defined in the new template revision.

    Exporting a Running Cluster to a New RKE Template and Revision​

    You can save an existing cluster's settings as an RKE template.

    This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to [use a newer version of the template.]

    To convert an existing cluster to use an RKE template,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that will be converted to use an RKE template. Click ⋮ > Save as RKE Template.
    3. Enter a name for the template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html index efdd008ea57..cdc8e1cb940 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html @@ -5,13 +5,13 @@ Overriding Template Settings | Rancher Manager - +
    Version: v2.0-v2.4

    Overriding Template Settings

    When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as Allow User Override.

    After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as Allow User Override. However, if the template is updated to a new revision that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster.

    When any parameter is set as Allow User Override on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time.

    The Allow User Override model of the RKE template is useful for situations such as:

    • Administrators know that some settings will need the flexibility to be frequently updated over time
    • End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html index eeded003ec6..03e5f22fbc9 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html @@ -5,13 +5,13 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.0-v2.4

    Pod Security Policies

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges).

    If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of Pod <NAME> is forbidden: unable to validate....

    How PSPs Work​

    You can assign PSPs at the cluster or project level.

    PSPs work through inheritance:

    • By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
    • Exception: Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
    • You can override the default PSP by assigning a different PSP directly to the project.

    Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Read more about Pod Security Policies in the Kubernetes Documentation.

    Default PSPs​

    Available as of v2.0.7

    Rancher ships with two default Pod Security Policies (PSPs): the restricted and unrestricted policies.

    Restricted​

    This policy is based on the Kubernetes example restricted policy. It significantly restricts what types of pods can be deployed to a cluster or project. This policy:

    • Prevents pods from running as a privileged user and prevents escalation of privileges.
    • Validates that server-required security mechanisms are in place (such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.

    Unrestricted​

    This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.

    Creating PSPs​

    Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.

    Requirements​

    Rancher can only assign PSPs for clusters that are launched using RKE.

    You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by editing the cluster.

    It is a best practice to set PSP at the cluster level.

    We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.

    Creating PSPs in the Rancher UI​

    1. From the Global view, select Security > Pod Security Policies from the main menu. Then click Add Policy.

      Step Result: The Add Policy form opens.

    2. Name the policy.

    3. Complete each section of the form. Refer to the Kubernetes documentation for more information on what each policy does.

    Configuration​

    The Kubernetes documentation on PSPs is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html index ba036e9866b..d29922d24b5 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html @@ -5,13 +5,13 @@ Configuring a Global Default Private Registry | Rancher Manager - +
    Version: v2.0-v2.4

    Configuring a Global Default Private Registry

    You might want to use a private container registry to share your custom base images within your organization. With a private registry, you can keep a private, consistent, and centralized source of truth for the container images that are used in your clusters.

    There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

    This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed.

    For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the air gapped Docker installation or air gapped Kubernetes installation instructions.

    If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to pass in the registry credentials through the advanced cluster options every time you create a new cluster.

    Setting a Private Registry with No Credentials as the Default Registry​

    1. Log into Rancher and configure the default administrator password.

    2. Go into the Settings view.

    3. Look for the setting called system-default-registry and choose Edit.

    4. Change the value to your registry (e.g. registry.yourdomain.com:port). Do not prefix the registry with http:// or https://.

    Result: Rancher will use your private registry to pull system images.

    Setting a Private Registry with Credentials when Deploying a Cluster​

    You can follow these steps to configure a private registry when you provision a cluster with Rancher:

    1. When you create a cluster through the Rancher UI, go to the Cluster Options section and click Show Advanced Options.
    2. In the Enable Private Registries section, click Enabled.
    3. Enter the registry URL and credentials.
    4. Click Save.

    Result: The new cluster will be able to pull images from the private registry.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html index 7926bbf8aa9..a39c24853ea 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html @@ -5,14 +5,14 @@ Cluster and Project Roles | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster and Project Roles

    Cluster and project roles define user authorization inside a cluster or project. You can manage these roles from the Global > Security > Roles page.

    Membership and Role Assignment​

    The projects and clusters accessible to non-administrative users is determined by membership. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.

    When you create a cluster or project, Rancher automatically assigns you as the Owner for it. Users assigned the Owner role can assign other users roles in the cluster or project.

    Note: Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.

    Cluster Roles​

    Cluster roles are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: Owner and Member.

    • Cluster Owner:

      These users have full control over the cluster and all resources in it.

    • Cluster Member:

      These users can view most cluster level resources and create new projects.

    Custom Cluster Roles​

    Rancher lets you assign custom cluster roles to a standard user instead of the typical Owner or Member roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.

    Cluster Role Reference​

    The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, Cluster Owner and Cluster Member.

    Built-in Cluster RoleOwnerMember
    Create Projects✓✓
    Manage Cluster Backups            ✓
    Manage Cluster Catalogs✓
    Manage Cluster Members✓
    Manage Nodes✓
    Manage Storage✓
    View All Projects✓
    View Cluster Catalogs✓✓
    View Cluster Members✓✓
    View Nodes✓✓

    For details on how each cluster role can access Kubernetes resources, you can go to the Global view in the Rancher UI. Then click Security > Roles and go to the Clusters tab. If you click an individual role, you can refer to the Grant Resources table to see all of the operations and resources that are permitted by the role.

    Note: When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Giving a Custom Cluster Role to a Cluster Member​

    After an administrator sets up a custom cluster role, cluster owners and admins can then assign those roles to cluster members.

    To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.

    To assign the role to a new cluster member,

    1. Go to the Cluster view, then go to the Members tab.
    2. Click Add Member. Then in the Cluster Permissions section, choose the custom cluster role that should be assigned to the member.
    3. Click Create.

    Result: The member has the assigned role.

    To assign any custom role to an existing cluster member,

    1. Go to the member you want to give the role to. Click the ⋮ > View in API.
    2. In the roleTemplateId field, go to the drop-down menu and choose the role you want to assign to the member. Click Show Request and Send Request.

    Result: The member has the assigned role.

    Project Roles​

    Project roles are roles that can be used to grant users access to a project. There are three primary project roles: Owner, Member, and Read Only.

    • Project Owner:

      These users have full control over the project and all resources in it.

    • Project Member:

      These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.

      Note:

      By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Read Only:

      These users can view everything in the project but cannot create, update, or delete anything.

      Caveat:

      Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the owner or member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    Custom Project Roles​

    Rancher lets you assign custom project roles to a standard user instead of the typical Owner, Member, or Read Only roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles.

    Project Role Reference​

    The following table lists each built-in custom project role available in Rancher and whether it is also granted by the Owner, Member, or Read Only role.

    Built-in Project RoleOwnerMemberRead Only
    Manage Project Members✓
    Create Namespaces✓✓
    Manage Config Maps✓✓
    Manage Ingress✓✓
    Manage Project Catalogs✓
    Manage Secrets✓✓
    Manage Service Accounts✓✓
    Manage Services✓✓
    Manage Volumes✓✓
    Manage Workloads✓✓
    View Secrets✓✓
    View Config Maps✓✓✓
    View Ingress✓✓✓
    View Project Members✓✓✓
    View Project Catalogs✓✓✓
    View Service Accounts✓✓✓
    View Services✓✓✓
    View Volumes✓✓✓
    View Workloads✓✓✓

    Notes:

    • Each project role listed above, including Owner, Member, and Read Only, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
    • The Manage Project Members role allows the project owner to manage any members of the project and grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually.

    Defining Custom Roles​

    As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.

    When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource will not override a broader grant defined in a role that the custom role is inheriting from.

    Default Cluster and Project Roles​

    By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either cluster owner or project owner. However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.

    There are two methods for changing default cluster/project roles:

    • Assign Custom Roles: Create a custom role for either your cluster or project, and then set the custom role as default.

    • Assign Individual Roles: Configure multiple cluster/project roles as default for assignment to the creating user.

      For example, instead of assigning a role that inherits other roles (such as cluster owner), you can choose a mix of individual roles (such as manage nodes and manage storage).

    Note:

    • Although you can lock a default role, the system still assigns the role to users who create a cluster/project.
    • Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.

    Configuring Default Roles for Cluster and Project Creators​

    You can change the cluster or project role(s) that are automatically assigned to the creating user.

    1. From the Global view, select Security > Roles from the main menu. Select either the Cluster or Project tab.

    2. Find the custom or individual role that you want to use as default. Then edit the role by selecting ⋮ > Edit.

    3. Enable the role as default.

      For Clusters
      1. From Cluster Creator Default, choose Yes: Default role for new cluster creation.
      2. Click Save.
      For Projects
      1. From Project Creator Default, choose Yes: Default role for new project creation.
      2. Click Save.

    4. If you want to remove a default role, edit the permission and select No from the default roles option.

    Result: The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the Cluster/Project Creator Default column.

    Cluster Membership Revocation Behavior​

    When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster and a project within the cluster, that standard user loses their cluster roles but retains their project roles. In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:

    If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html index 07cccb873ab..a50953b64f2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html @@ -5,13 +5,13 @@ Custom Roles | Rancher Manager - +
    Version: v2.0-v2.4

    Custom Roles

    Within Rancher, roles determine what actions a user can make within a cluster or project.

    Note that roles are different from permissions, which determine what clusters and projects you can access.

    Prerequisites​

    To complete the tasks on this page, one of the following permissions are required:

    Creating A Custom Role for a Cluster or Project​

    While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.

    The steps to add custom roles differ depending on the version of Rancher.

    1. From the Global view, select Security > Roles from the main menu.

    2. Select a tab to determine the scope of the roles you're adding. The tabs are:

    • Cluster: The role is valid for assignment when adding/managing members to only clusters.
    • Project: The role is valid for assignment when adding/managing members to only projects.

    1. Click Add Cluster/Project Role.

    2. Name the role.

    3. Optional: Choose the Cluster/Project Creator Default option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.

      Out of the box, the Cluster Creator Default and the Project Creator Default roles are Cluster Owner and Project Owner respectively.

    4. Use the Grant Resources options to assign individual Kubernetes API endpoints to the role.

      When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

      You can also choose the individual cURL methods (Create, Delete, Get, etc.) available for use with each endpoint you assign.

    5. Use the Inherit from a Role options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.

    6. Click Create.

    Creating a Custom Global Role​

    Available as of v2.4.0

    Creating a Custom Global Role that Copies Rules from an Existing Role​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.

    The custom global role can then be assigned to a user or group so that the custom global role takes effect the first time the user or users sign into Rancher.

    To create a custom global role based on an existing role,

    1. Go to the Global view and click Security > Roles.

    2. On the Global tab, go to the role that the custom global role will be based on. Click ⋮ (…) > Clone.

    3. Enter a name for the role.

    4. Optional: To assign the custom role default for new users, go to the New User Default section and click Yes: Default role for new users.

    5. In the Grant Resources section, select the Kubernetes resource operations that will be enabled for users with the custom role.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

    6. Click Save.

    Creating a Custom Global Role that Does Not Copy Rules from Another Role​

    Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:

    1. Go to the Global view and click Security > Roles.

    2. On the Global tab, click Add Global Role.

    3. Enter a name for the role.

    4. Optional: To assign the custom role default for new users, go to the New User Default section and click Yes: Default role for new users.

    5. In the Grant Resources section, select the Kubernetes resource operations that will be enabled for users with the custom role.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

    6. Click Save.

    Deleting a Custom Global Role​

    Available as of v2.4.0

    When deleting a custom global role, all global role bindings with this custom role are deleted.

    If a user is only assigned one custom global role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.

    Custom global roles can be deleted, but built-in roles cannot be deleted.

    To delete a custom global role,

    1. Go to the Global view and click Security > Roles.
    2. On the Global tab, go to the custom global role that should be deleted and click ⋮ (…) > Delete.
    3. Click Delete.

    Assigning a Custom Global Role to a Group​

    Available as of v2.4.0

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.

    When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have their individual Standard User role.

    Prerequisites: You can only assign a global role to a group if:

    To assign a custom global role to a group, follow these steps:

    1. From the Global view, go to Security > Groups.
    2. Click Assign Global Role.
    3. In the Select Group To Add field, choose the existing group that will be assigned the custom global role.
    4. In the Custom section, choose any custom global role that will be assigned to the group.
    5. Optional: In the Global Permissions or Built-in sections, select any additional permissions that the group should have.
    6. Click Create.

    Result: The custom global role will take effect when the users in the group log into Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html index 8705a1ffd6f..cc8f14ba5b5 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html @@ -5,13 +5,13 @@ Global Permissions | Rancher Manager - +
    Version: v2.0-v2.4

    Global Permissions

    Permissions are individual access rights that you can assign when selecting a custom permission for a user.

    Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are three default global permissions: Administrator, Standard User and User-base.

    • Administrator: These users have full control over the entire Rancher system and all clusters within it.

    • **Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.

    • User-Base: User-Base users have login-access only.

    You cannot update or delete the built-in Global Permissions.

    Global Permission Assignment

    Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.

    Global Permissions for New Local Users​

    When you create a new local user, you assign them a global permission as you complete the Add User form.

    To see the default permissions for new users, go to the Global view and click Security > Roles. On the Global tab, there is a column named New User Default. When adding a new local user, the user receives all default global permissions that are marked as checked in this column. You can change the default global permissions to meet your needs.

    Global Permissions for Users with External Authentication​

    When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the New User Default global permissions. By default, Rancher assigns the Standard User permission for new users.

    To see the default permissions for new users, go to the Global view and click Security > Roles. On the Global tab, there is a column named New User Default. When adding a new local user, the user receives all default global permissions that are marked as checked in this column, and you can change them to meet your needs.

    Permissions can be assigned to an individual user with these steps.

    As of Rancher v2.4.0, you can assign a role to everyone in the group at the same time if the external authentication provider supports groups.

    Custom Global Permissions

    Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.

    When a user from an external authentication source signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default user permission. The standard user permission allows users to login and create clusters.

    However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of Administrator or Standard User, you can assign them a more restrictive set of custom global permissions.

    The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role.

    Administrators can enforce custom global permissions in multiple ways:

    Custom Global Permissions Reference​

    The following table lists each custom global permission available and whether it is included in the default global permissions, Administrator, Standard User and User-Base.

    Custom Global PermissionAdministratorStandard UserUser-Base
    Create Clusters✓✓
    Create RKE Templates✓✓
    Manage Authentication✓
    Manage Catalogs✓
    Manage Cluster Drivers✓
    Manage Node Drivers✓
    Manage PodSecurityPolicy Templates✓
    Manage Roles✓
    Manage Settings✓
    Manage Users✓
    Use Catalog Templates✓✓
    User Base* (Basic log-in access)✓✓

    *This role has two names:

    • When you go to the Users tab and edit a user's global role, this role is called Login Access in the custom global permissions list.
    • When you go to the Security tab and edit the roles from the roles page, this role is called User Base.

    For details on which Kubernetes resources correspond to each global permission, you can go to the Global view in the Rancher UI. Then click Security > Roles and go to the Global tab. If you click an individual role, you can refer to the Grant Resources table to see all of the operations and resources that are permitted by the role.

    Notes:

    • Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at /v3/globalRoles.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Configuring Default Global Permissions​

    If you want to restrict the default permissions for new users, you can remove the user permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.

    Note: Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.

    To change the default global permissions that are assigned to external users upon their first log in, follow these steps:

    1. From the Global view, select Security > Roles from the main menu. Make sure the Global tab is selected.

    2. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting ⋮ > Edit.

    3. If you want to add the permission as a default, Select Yes: Default role for new users and then click Save.

    4. If you want to remove a default permission, edit the permission and select No from New User Default.

    Result: The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the New User Default column.

    Configuring Global Permissions for Individual Users​

    To configure permission for a user,

    1. Go to the Users tab.

    2. On this page, go to the user whose access level you want to change and click ⋮ > Edit.

    3. In the Global Permissions section, click Custom.

    4. Check the boxes for each subset of permissions you want the user to have access to.

    5. Click Save.

    Result: The user's global permissions have been updated.

    Configuring Global Permissions for Groups​

    Available as of v2.4.0

    If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.

    After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.

    For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator refreshes the group memberships.

    For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the New User Default global permissions. By default, the New User Default permissions are equivalent to the Standard User global role, but the default permissions can be configured.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as New User Default. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator refreshes group memberships, whichever comes first.

    Prerequisites: You can only assign a global role to a group if:

    To assign a custom global role to a group, follow these steps:

    1. From the Global view, go to Security > Groups.
    2. Click Assign Global Role.
    3. In the Select Group To Add field, choose the existing group that will be assigned the custom global role.
    4. In the Global Permissions, Custom, and/or Built-in sections, select the permissions that the group should have.
    5. Click Create.

    Result: The custom global role will take effect when the users in the group log into Rancher.

    Refreshing Group Memberships​

    When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.

    To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.

    An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.

    To refresh group memberships,

    1. From the Global view, click Security > Users.
    2. Click Refresh Group Memberships.

    Result: Any changes to the group members' permissions will take effect.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html index 9c8cb0ef3fa..62f7feb6793 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html @@ -5,13 +5,13 @@ Locked Roles | Rancher Manager - +
    Version: v2.0-v2.4

    Locked Roles

    You can set roles to a status of locked. Locking roles prevent them from being assigned users in the future.

    Locked roles:

    • Cannot be assigned to users that don't already have it assigned.

    • Are not listed in the Member Roles drop-down when you are adding a user to a cluster or project.

    • Do not affect users assigned the role before you lock the role. These users retain access that the role provides.

      Example: let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.

      To enforce it, before you add new users to the cluster, you should lock the following roles: Cluster Owner, Cluster Member, and Create Projects. Then you could create a new custom role that includes the same permissions as a Cluster Member, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.

    Roles can be locked by the following users:

    • Any user assigned the Administrator global permission.
    • Any user assigned the Custom Users permission, along with the Manage Roles role.

    Locking/Unlocking Roles​

    If you want to prevent a role from being assigned to users, you can set it to a status of locked.

    You can lock roles in two contexts:

    1. From the Global view, select Security > Roles.

    2. From the role that you want to lock (or unlock), select ⋮ > Edit.

    3. From the Locked option, choose the Yes or No radio button. Then click Save.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html index efc98bdc3d9..861b4512f93 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html @@ -5,13 +5,13 @@ Configure Alerts for Periodic Scan on a Schedule | Rancher Manager - +
    Version: v2.0-v2.4

    Configure Alerts for Periodic Scan on a Schedule

    Rancher provides a set of alerts for cluster scans. which are not configured to have notifiers by default:

    • A manual cluster scan was completed
    • A manual cluster scan has failures
    • A scheduled cluster scan was completed
    • A scheduled cluster scan has failures
    Prerequisite

    You need to configure a notifier before configuring, sending, or receiving alerts.

    To activate an existing alert for a CIS scan result,

    1. From the cluster view in Rancher, click Tools > Alerts.
    2. Go to the section called A set of alerts for cluster scans.
    3. Go to the alert you want to activate and click ⋮ > Activate.
    4. Go to the alert rule group A set of alerts for cluster scans and click ⋮ > Edit.
    5. Scroll down to the Alert section. In the To field, select the notifier that you would like to use for sending alert notifications.
    6. Optional: To limit the frequency of the notifications, click on Show advanced options and configure the time interval of the alerts.
    7. Click Save.

    Result: The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.

    To create a new alert,

    1. Go to the cluster view and click Tools > CIS Scans.
    2. Click Add Alert.
    3. Fill out the form.
    4. Enter a name for the alert.
    5. In the Is field, set the alert to be triggered when a scan is completed or when a scan has a failure.
    6. In the Send a field, set the alert as a Critical, Warning, or Info alert level.
    7. Choose a notifier for the alert.

    Result: The alert is created and activated. The notifications will be triggered when the a scan is run on a cluster and the active alerts have satisfied conditions.

    For more information about alerts, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.html index 622bb132bc8..44e49205b97 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/delete-a-report.html @@ -5,13 +5,13 @@ Delete a Report | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.html index 119e12bc44e..970bec7c60b 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/download-a-report.html @@ -5,13 +5,13 @@ Download a Report | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html index 69767c6bbe0..361bfa03133 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html @@ -5,13 +5,13 @@ Run a Scan Periodically on a Schedule | Rancher Manager - +
    Version: v2.0-v2.4

    Run a Scan Periodically on a Schedule

    Recurring scans can be scheduled to run on any RKE Kubernetes cluster.

    To enable recurring scans, edit the advanced options in the cluster configuration during cluster creation or after the cluster has been created.

    To schedule scans for an existing cluster:

    1. Go to the cluster view in Rancher.
    2. Click Tools > CIS Scans.
    3. Click Add Schedule. This takes you to the section of the cluster editing page that is applicable to configuring a schedule for CIS scans. (This section can also be reached by going to the cluster view, clicking ⋮ > Edit, and going to the Advanced Options.)
    4. In the CIS Scan Enabled field, click Yes.defined in a separate ConfigMap
    5. In the CIS Scan Interval (cron) job, enter a cron expression to define how often the cluster will be scanned.
    6. In the CIS Scan Report Retention field, enter the number of past reports that should be kept.

    Result: The security scan will run and generate reports at the scheduled intervals.

    The test schedule can be configured in the cluster.yml:

    scheduled_cluster_scan:
        enabled: true
        scan_config:
            cis_scan_config:
                override_benchmark_version: rke-cis-1.4
                profile: permissive
        schedule_config:
            cron_schedule: 0 0 * * *
            retention: 24
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html index cb8deedae85..4430876c4c2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html @@ -5,13 +5,13 @@ Run a Scan | Rancher Manager - +
    Version: v2.0-v2.4

    Run a Scan

    1. From the cluster view in Rancher, click Tools > CIS Scans.
    2. Click Run Scan.
    3. Choose a CIS scan profile.

    Result: A report is generated and displayed in the CIS Scans page. To see details of the report, click the report's name.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html index c45b2991b41..dee23feffc7 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html @@ -5,13 +5,13 @@ Skip Tests | Rancher Manager - +
    Version: v2.0-v2.4

    Skip Tests

    You can define a set of tests that will be skipped by the CIS scan when the next report is generated.

    These tests will be skipped for subsequent CIS scans, including both manually triggered and scheduled scans, and the tests will be skipped with any profile.

    The skipped tests will be listed alongside the test profile name in the cluster configuration options when a test profile is selected for a recurring cluster scan. The skipped tests will also be shown every time a scan is triggered manually from the Rancher UI by clicking Run Scan. The display of skipped tests allows you to know ahead of time which tests will be run in each scan.

    To skip tests, you will need to define them in a Kubernetes ConfigMap resource. Each skipped CIS scan test is listed in the ConfigMap alongside the version of the CIS benchmark that the test belongs to.

    To skip tests by editing a ConfigMap resource,

    1. Create a security-scan namespace.

    2. Create a ConfigMap named security-scan-cfg.

    3. Enter the skip information under the key config.json in the following format:

      {
        "skip": {
          "rke-cis-1.4": [
            "1.1.1",
            "1.2.2"
          ]
        }
      }

      In the example above, the CIS benchmark version is specified alongside the tests to be skipped for that version.

    Result: These tests will be skipped on subsequent scans that use the defined CIS Benchmark version.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster-with-psp.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster-with-psp.html index 3d6468b32ba..36854c62f6f 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster-with-psp.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster-with-psp.html @@ -5,13 +5,13 @@ Enable Istio with Pod Security Policies | Rancher Manager - +
    Version: v2.0-v2.4

    Enable Istio with Pod Security Policies

    Note: The following guide is only for RKE provisioned clusters.

    If you have restrictive Pod Security Policies enabled, then Istio may not be able to function correctly, because it needs certain permissions in order to install itself and manage pod infrastructure. In this section, we will configure a cluster with PSPs enabled for an Istio install, and also set up the Istio CNI plugin.

    The Istio CNI plugin removes the need for each application pod to have a privileged NET_ADMIN container. For further information, see the Istio CNI Plugin docs. Please note that the Istio CNI Plugin is in alpha.

    1. Configure the System Project Policy to allow Istio install​

    1. From the main menu of the Dashboard, select Projects/Namespaces.
    2. Find the Project: System project and select the ⋮ > Edit.
    3. Change the Pod Security Policy option to be unrestricted, then click Save.

    2. Install the CNI Plugin in the System Project​

    1. From the main menu of the Dashboard, select Projects/Namespaces.
    2. Select the Project: System project.
    3. Choose Tools > Catalogs in the navigation bar.
    4. Add a catalog with the following:
      1. Name: istio-cni
      2. Catalog URL: https://github.com/istio/cni
      3. Branch: The branch that matches your current release, for example: release-1.4.
    5. From the main menu select Apps
    6. Click Launch and select istio-cni
    7. Update the namespace to be "kube-system"
    8. In the answers section, click "Edit as YAML" and paste in the following, then click launch:
    ---
      logLevel: "info"
      excludeNamespaces:
        - "istio-system"
        - "kube-system"

    3. Install Istio​

    Follow the primary instructions, adding a custom answer: istio_cni.enabled: true.

    After Istio has finished installing, the Apps page in System Projects should show both istio and istio-cni applications deployed successfully. Sidecar injection will now be functional.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html index ba2fa6e7358..a1a57b0b1ca 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html @@ -5,13 +5,13 @@ 1. Enable Istio in the Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    1. Enable Istio in the Cluster

    This cluster uses the default Nginx controller to allow traffic into the cluster.

    A Rancher administrator or cluster owner can configure Rancher to deploy Istio in a Kubernetes cluster.

    Prerequisites

    This guide assumes you have already installed Rancher, and you have already provisioned a separate Kubernetes cluster on which you will install Istio.

    The nodes in your cluster must meet the CPU and memory requirements.

    The workloads and services that you want to be controlled by Istio must meet Istio's requirements.

    If the cluster has a Pod Security Policy enabled there are additional prerequisites steps

    Enable Istio in the Cluster

    1. From the Global view, navigate to the cluster where you want to enable Istio.
    2. Click Tools > Istio.
    3. Optional: Configure member access and resource limits for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
    4. Click Enable.
    5. Click Save.

    Result: Istio is enabled at the cluster level.

    The Istio application, cluster-istio, is added as an application to the cluster's system project.

    When Istio is enabled in the cluster, the label for Istio sidecar auto injection,istio-injection=enabled, will be automatically added to each new namespace in this cluster. This automatically enables Istio sidecar injection in all new workloads that are deployed in those namespaces. You will need to manually enable Istio in preexisting namespaces and workloads.

    Next: Enable Istio in a Namespace​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html index 2468b648fbc..836003e5f46 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html @@ -5,13 +5,13 @@ 2. Enable Istio in a Namespace | Rancher Manager - +
    Version: v2.0-v2.4

    2. Enable Istio in a Namespace

    You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.

    This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.

    Prerequisite: To enable Istio in a namespace, the cluster must have Istio enabled.

    1. In the Rancher UI, go to the cluster view. Click the Projects/Namespaces tab.
    2. Go to the namespace where you want to enable the Istio sidecar auto injection and click the ⋮.
    3. Click Edit.
    4. In the Istio sidecar auto injection section, click Enable.
    5. Click Save.

    Result: The namespace now has the label istio-injection=enabled. All new workloads deployed in this namespace will have the Istio sidecar injected by default.

    Verifying that Automatic Istio Sidecar Injection is Enabled​

    To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the Containers section, you should see the istio-proxy container.

    Excluding Workloads from Being Injected with the Istio Sidecar​

    If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:

    sidecar.istio.io/inject: “false”

    To add the annotation to a workload,

    1. From the Global view, open the project that has the workload that should not have the sidecar.
    2. Click Resources > Workloads.
    3. Go to the workload that should not have the sidecar and click ⋮ > Edit.
    4. Click Show Advanced Options. Then expand the Labels & Annotations section.
    5. Click Add Annotation.
    6. In the Key field, enter sidecar.istio.io/inject.
    7. In the Value field, enter false.
    8. Click Save.

    Result: The Istio sidecar will not be injected into the workload.

    NOTE: If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.

    Next: Select the Nodes ​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html index 2b7ccc65cd3..a919c30433e 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html @@ -5,13 +5,13 @@ 7. Generate and View Traffic | Rancher Manager - +
    Version: v2.0-v2.4

    7. Generate and View Traffic

    This section describes how to view the traffic that is being managed by Istio.

    The Kiali Traffic Graph

    Rancher integrates a Kiali graph into the Rancher UI. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.

    To see the traffic graph,

    1. From the project view in Rancher, click Resources > Istio.
    2. Go to the Traffic Graph tab. This tab has the Kiali network visualization integrated into the UI.

    If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to v1 and v3 of the reviews service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.

    For additional tools and visualizations, you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.

    Viewing Traffic Metrics

    Istio’s monitoring features provide visibility into the performance of all your services.

    1. From the project view in Rancher, click Resources > Istio.
    2. Go to the Traffic Metrics tab. After traffic is generated in your cluster, you should be able to see metrics for Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count and Request Duration.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.html index d360ac51bb8..8b648e4bd03 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/node-selectors.html @@ -5,13 +5,13 @@ 3. Select the Nodes Where Istio Components Will be Deployed | Rancher Manager - +
    Version: v2.0-v2.4

    3. Select the Nodes Where Istio Components Will be Deployed

    Prerequisite: Your cluster needs a worker node that can designated for Istio. The worker node should meet the resource requirements.

    This section describes how use node selectors to configure Istio components to be deployed on a designated node.

    In larger deployments, it is strongly advised that Istio's infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.

    Adding a Label to the Istio Node

    First, add a label to the node where Istio components should be deployed. This label can have any key-value pair. For this example, we will use the key istio and the value enabled.

    1. From the cluster view, go to the Nodes tab.
    2. Go to a worker node that will host the Istio components and click ⋮ > Edit.
    3. Expand the Labels & Annotations section.
    4. Click Add Label.
    5. In the fields that appear, enter istio for the key and enabled for the value.
    6. Click Save.

    Result: A worker node has the label that will allow you to designate it for Istio components.

    Configuring Istio Components to Use the Labeled Node

    Configure each Istio component to be deployed to the node with the Istio label. Each Istio component can be configured individually, but in this tutorial, we will configure all of the components to be scheduled on the same node for the sake of simplicity.

    For larger deployments, it is recommended to schedule each component of Istio onto separate nodes.

    1. From the cluster view, click Tools > Istio.
    2. Expand the Pilot section and click Add Selector in the form that appears. Enter the node selector label that you added to the Istio node. In our case, we are using the key istio and the value enabled.
    3. Repeat the previous step for the Mixer and Tracing sections.
    4. Click Save.

    Result: The Istio components will be deployed on the Istio node.

    Next: Add Deployments and Services​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html index 1c977854bba..9957b332723 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html @@ -5,13 +5,13 @@ 5. Set up the Istio Gateway | Rancher Manager - +
    Version: v2.0-v2.4

    5. Set up the Istio Gateway

    The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.

    You can use the NGINX ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.

    To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two ingresses.

    You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.

    You can route traffic into the service mesh with a load balancer or just Istio's NodePort gateway. This section describes how to set up the NodePort gateway.

    For more information on the Istio gateway, refer to the Istio documentation.

    In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.

    Enable the Istio Gateway

    The ingress gateway is a Kubernetes service that will be deployed in your cluster. There is only one Istio gateway per cluster.

    1. Go to the cluster where you want to allow outside traffic into Istio.
    2. Click Tools > Istio.
    3. Expand the Ingress Gateway section.
    4. Under Enable Ingress Gateway, click True. The default type of service for the Istio gateway is NodePort. You can also configure it as a load balancer.
    5. Optionally, configure the ports, service types, node selectors and tolerations, and resource requests and limits for this service. The default resource requests for CPU and memory are the minimum recommended resources.
    6. Click Save.

    Result: The gateway is deployed, which allows Istio to receive traffic from outside the cluster.

    Add a Kubernetes Gateway that Points to the Istio Gateway

    To allow traffic to reach Ingress, you will also need to provide a Kubernetes gateway resource in your YAML that points to Istio's implementation of the ingress gateway to the cluster.

    1. Go to the namespace where you want to deploy the Kubernetes gateway and click Import YAML.
    2. Upload the gateway YAML as a file or paste it into the form. An example gateway YAML is provided below.
    3. Click Import.
    apiVersion: networking.istio.io/v1alpha3
    kind: Gateway
    metadata:
      name: bookinfo-gateway
    spec:
      selector:
        istio: ingressgateway # use istio default controller
      servers:
        - port:
            number: 80
            name: http
            protocol: HTTP
          hosts:
            - "*"
    ---
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: bookinfo
    spec:
      hosts:
      - "*"
      gateways:
      - bookinfo-gateway
      http:
      - match:
        - uri:
            exact: /productpage
        - uri:
            prefix: /static
        - uri:
            exact: /login
        - uri:
            exact: /logout
        - uri:
            prefix: /api/v1/products
        route:
        - destination:
            host: productpage
            port:
              number: 9080

    Result: You have configured your gateway resource so that Istio can receive traffic from outside the cluster.

    Confirm that the resource exists by running:

    kubectl get gateway -A

    The result should be something like this:

    NAME               AGE
    bookinfo-gateway   64m

    Access the ProductPage Service from a Web Browser​

    To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:

    http://<IP of Istio controller>:<Port of istio controller>/productpage

    To get the ingress gateway URL and port,

    1. Go to the System project in your cluster.
    2. Within the System project, go to Resources > Workloads then scroll down to the istio-system namespace.
    3. Within istio-system, there is a workload named istio-ingressgateway. Under the name of this workload, you should see links, such as 80/tcp.
    4. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append /productpage to the URL.

    Result: You should see the BookInfo app in the web browser.

    For help inspecting the Istio controller URL and ports, try the commands the Istio documentation.

    Troubleshooting

    The official Istio documentation suggests kubectl commands to inspect the correct ingress host and ingress port for external requests.

    Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller​

    You can try the steps in this section to make sure the Kubernetes gateway is configured properly.

    In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is istio and the value is ingressgateway. To make sure the label is appropriate for the gateway, do the following:

    1. Go to the System project in your cluster.
    2. Within the System project, go to the namespace istio-system.
    3. Within istio-system, there is a workload named istio-ingressgateway.
    4. Click the name of this workload and go to the Labels and Annotations section. You should see that it has the key istio and the value ingressgateway. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.

    Next: Set up Istio's Components for Traffic Management​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html index 4a9f8cabc73..4cf9c0274a5 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html @@ -5,13 +5,13 @@ 6. Set up Istio's Components for Traffic Management | Rancher Manager - +
    Version: v2.0-v2.4

    6. Set up Istio's Components for Traffic Management

    A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are virtual services and destination rules.

    • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
    • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.

    This section describes how to add an example virtual service that corresponds to the reviews microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the reviews service.

    In this example, we take the traffic to the reviews service and intercept it so that 50 percent of it goes to v1 of the service and 50 percent goes to v2.

    After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.

    To deploy the virtual service and destination rules for the reviews service,

    1. Go to the project view and click Import YAML.
    2. Copy resources below into the form.
    3. Click Import.
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: reviews
    spec:
      hosts:
      - reviews
      http:
      - route:
        - destination:
            host: reviews
            subset: v1
          weight: 50
        - destination:
            host: reviews
            subset: v3
          weight: 50
    ---
    apiVersion: networking.istio.io/v1alpha3
    kind: DestinationRule
    metadata:
      name: reviews
    spec:
      host: reviews
      subsets:
      - name: v1
        labels:
          version: v1
      - name: v2
        labels:
          version: v2
      - name: v3
        labels:
          version: v3

    Result: When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the reviews service is divided evenly between v1 and v3.

    Next: Generate and View Traffic​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html index a1aa71df255..fc6502b855b 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html @@ -5,13 +5,13 @@ 4. Add Deployments and Services with the Istio Sidecar | Rancher Manager - +
    Version: v2.0-v2.4

    4. Add Deployments and Services with the Istio Sidecar

    Prerequisite: To enable Istio for a workload, the cluster and namespace must have Istio enabled.

    Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.

    To inject the Istio sidecar on an existing workload in the namespace, go to the workload, click the ⋮, and click Redeploy. When the workload is redeployed, it will have the Envoy sidecar automatically injected.

    Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see istio-init and istio-proxy alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.

    3. Add Deployments and Services​

    Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.

    1. Go to the project inside the cluster you want to deploy the workload on.
    2. In Workloads, click Import YAML.
    3. Copy the below resources into the form.
    4. Click Import.

    This will set up the following sample resources from Istio's example BookInfo app:

    Details service and deployment:

    • A details Service
    • A ServiceAccount for bookinfo-details
    • A details-v1 Deployment

    Ratings service and deployment:

    • A ratings Service
    • A ServiceAccount for bookinfo-ratings
    • A ratings-v1 Deployment

    Reviews service and deployments (three versions):

    • A reviews Service
    • A ServiceAccount for bookinfo-reviews
    • A reviews-v1 Deployment
    • A reviews-v2 Deployment
    • A reviews-v3 Deployment

    Productpage service and deployment:

    This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.

    • A productpage service
    • A ServiceAccount for bookinfo-productpage
    • A productpage-v1 Deployment

    Resource YAML​

    # Copyright 2017 Istio Authors
    #
    #   Licensed under the Apache License, Version 2.0 (the "License");
    #   you may not use this file except in compliance with the License.
    #   You may obtain a copy of the License at
    #
    #       http://www.apache.org/licenses/LICENSE-2.0
    #
    #   Unless required by applicable law or agreed to in writing, software
    #   distributed under the License is distributed on an "AS IS" BASIS,
    #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    #   See the License for the specific language governing permissions and
    #   limitations under the License.

    ##################################################################################################
    # Details service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: details
      labels:
        app: details
        service: details
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: details
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-details
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: details-v1
      labels:
        app: details
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: details
          version: v1
      template:
        metadata:
          labels:
            app: details
            version: v1
        spec:
          serviceAccountName: bookinfo-details
          containers:
          - name: details
            image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Ratings service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: ratings
      labels:
        app: ratings
        service: ratings
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: ratings
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-ratings
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ratings-v1
      labels:
        app: ratings
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: ratings
          version: v1
      template:
        metadata:
          labels:
            app: ratings
            version: v1
        spec:
          serviceAccountName: bookinfo-ratings
          containers:
          - name: ratings
            image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Reviews service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: reviews
      labels:
        app: reviews
        service: reviews
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: reviews
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-reviews
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v1
      labels:
        app: reviews
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v1
      template:
        metadata:
          labels:
            app: reviews
            version: v1
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v2
      labels:
        app: reviews
        version: v2
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v2
      template:
        metadata:
          labels:
            app: reviews
            version: v2
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v3
      labels:
        app: reviews
        version: v3
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v3
      template:
        metadata:
          labels:
            app: reviews
            version: v3
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Productpage services
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: productpage
      labels:
        app: productpage
        service: productpage
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: productpage
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-productpage
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: productpage-v1
      labels:
        app: productpage
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: productpage
          version: v1
      template:
        metadata:
          labels:
            app: productpage
            version: v1
        spec:
          serviceAccountName: bookinfo-productpage
          containers:
          - name: productpage
            image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---

    Next: Set up the Istio Gateway​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html index 3a13be18755..4634f14e9b8 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html @@ -5,14 +5,14 @@ Adding Users to Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Adding Users to Clusters

    If you want to provide a user with access and permissions to all projects, nodes, and resources within a cluster, assign the user a cluster membership.

    Tip: Want to provide a user with access to a specific project within a cluster? See Adding Project Members instead.

    There are two contexts where you can add cluster members:

    • Adding Members to a New Cluster

      You can add members to a cluster as you create it (recommended if possible).

    • Adding Members to an Existing Cluster

      You can always add members to a cluster after a cluster is provisioned.

    Editing Cluster Membership​

    Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.

    1. From the Global view, open the cluster that you want to add members to.

    2. From the main menu, select Members. Then click Add Member.

    3. Search for the user or group that you want to add to the cluster.

      If external authentication is configured:

    4. Assign the user or group Cluster roles.

      What are Cluster Roles?

      Tip: For Custom Roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the cluster.

    • To revoke cluster membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html index d0502df4e5a..935a12c85ae 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html @@ -5,13 +5,13 @@ How the Authorized Cluster Endpoint Works | Rancher Manager - +
    Version: v2.0-v2.4

    How the Authorized Cluster Endpoint Works

    This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for how to set up kubectl to directly access a cluster.

    About the kubeconfig File​

    The kubeconfig file is a file used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients).

    This kubeconfig file and its contents are specific to the cluster you are viewing. It can be downloaded from the cluster view in Rancher. You will need a separate kubeconfig file for each cluster that you have access to in Rancher.

    After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes contexts to access your downstream cluster.

    Available as of v2.4.6

    If admins have enforced TTL on kubeconfig tokens, the kubeconfig file requires rancher cli to be present in your PATH.

    Two Authentication Methods for RKE Clusters​

    If the cluster is not an RKE cluster, the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster.

    For RKE clusters, the kubeconfig file allows you to be authenticated in two ways:

    • Through the Rancher server authentication proxy: Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access.
    • Directly with the downstream cluster's API server: RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the kube-api-auth microservice) that Rancher set up.

    This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.

    To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on this page.

    These methods of communicating with downstream Kubernetes clusters are also explained in the architecture page in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.

    About the kube-api-auth Authentication Webhook​

    The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint, which is only available for RKE clusters. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

    During cluster provisioning, the file /etc/kubernetes/kube-api-authn-webhook.yaml is deployed and kube-apiserver is configured with --authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml. This configures the kube-apiserver to query http://127.0.0.1:6440/v1/authenticate to determine authentication for bearer tokens.

    The scheduling rules for kube-api-auth are listed below:

    Applies to v2.3.0 and higher

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    kube-api-authbeta.kubernetes.io/os:NotIn:windows
    node-role.kubernetes.io/controlplane:In:"true"    		noneoperator:Exists
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html index 9b3a0900e7e..2d6d45d4062 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html @@ -5,13 +5,13 @@ Access a Cluster with Kubectl and kubeconfig | Rancher Manager - +
    Version: v2.0-v2.4

    Access a Cluster with Kubectl and kubeconfig

    This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.

    For more information on using kubectl, see Kubernetes Documentation: Overview of kubectl.

    Accessing Clusters with kubectl Shell in the Rancher UI​

    You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.

    1. From the Global view, open the cluster that you want to access with kubectl.

    2. Click Launch kubectl. Use the window that opens to interact with your Kubernetes cluster.

    Accessing Clusters with kubectl from Your Workstation​

    This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.

    This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.

    Prerequisites: These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official Kubernetes documentation.

    1. Log into Rancher. From the Global view, open the cluster that you want to access with kubectl.
    2. Click Kubeconfig File.
    3. Copy the contents displayed to your clipboard.
    4. Paste the contents into a new file on your local computer. Move the file to ~/.kube/config. Note: The default location that kubectl uses for the kubeconfig file is ~/.kube/config, but you can use any directory and specify it using the --kubeconfig flag, as in this command:
      kubectl --kubeconfig /custom/path/kube.config get pods
    5. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.

    Note on Resources Created Using kubectl​

    Rancher will discover and show resources created by kubectl. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.

    Authenticating Directly with a Downstream Cluster​

    This section intended to help you set up an alternative method to access an RKE cluster.

    This method is only available for RKE clusters that have the authorized cluster endpoint enabled. When Rancher creates this RKE cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to this page.

    We recommend that as a best practice, you should set up this method to access your RKE cluster, so that just in case you can’t connect to Rancher, you can still access the cluster.

    Prerequisites: The following steps assume that you have created a Kubernetes cluster and followed the steps to connect to your cluster with kubectl from your workstation.

    To find the name of the context(s) in your downloaded kubeconfig file, run:

    kubectl config get-contexts --kubeconfig /custom/path/kube.config
    CURRENT   NAME                        CLUSTER                     AUTHINFO     NAMESPACE
    *         my-cluster                  my-cluster                  user-46tmn
              my-cluster-controlplane-1   my-cluster-controlplane-1   user-46tmn

    In this example, when you use kubectl with the first context, my-cluster, you will be authenticated through the Rancher server.

    With the second context, my-cluster-controlplane-1, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE cluster directly.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below.

    When kubectl works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy.

    Connecting Directly to Clusters with FQDN Defined​

    If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named <CLUSTER_NAME>-fqdn. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-fqdn get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-fqdn get pods

    Connecting Directly to Clusters without FQDN Defined​

    If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named <CLUSTER_NAME>-<NODE_NAME>. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-<NODE_NAME> get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAME> get pods
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html index 6eb196b7a15..81fcced2998 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html @@ -5,13 +5,13 @@ Adding a Pod Security Policy | Rancher Manager - +
    Version: v2.0-v2.4

    Adding a Pod Security Policy

    Prerequisite: The options below are available only for clusters that are launched using RKE.

    When your cluster is running pods with security-sensitive configurations, assign it a pod security policy, which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running.

    You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster.

    1. From the Global view, find the cluster to which you want to apply a pod security policy. Select ⋮ > Edit.

    2. Expand Cluster Options.

    3. From Pod Security Policy Support, select Enabled.

      Note: This option is only available for clusters provisioned by RKE.

    4. From the Default Pod Security Policy drop-down, select the policy you want to apply to the cluster.

      Rancher ships with policies of restricted and unrestricted, although you can create custom policies as well.

    5. Click Save.

    Result: The pod security policy is applied to the cluster and any projects within the cluster.

    Note: Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run.

    To check if a running workload passes your pod security policy, clone or upgrade it.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html index 5230fe152d0..42182da060e 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html @@ -5,7 +5,7 @@ Assigning Pod Security Policies | Rancher Manager - + @@ -14,7 +14,7 @@ Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see Creating Pod Security Policies. Note: For security purposes, we recommend assigning a PSP as you create your clusters.

    To enable a default Pod Security Policy, set the Pod Security Policy Support option to Enabled, and then make a selection from the Default Pod Security Policy drop-down.

    When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.html index 6cec6d61db3..de91c27f8cb 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/backing-up-etcd.html @@ -5,13 +5,13 @@ Backing up a Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Backing up a Cluster

    Available as of v2.2.0

    In the Rancher UI, etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed.

    Rancher recommends configuring recurrent etcd snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.

    Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    How Snapshots Work

    Snapshot Components​

    When Rancher creates a snapshot, it includes three components:

    • The cluster data in etcd
    • The Kubernetes version
    • The cluster configuration in the form of the cluster.yml

    Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version.

    The multiple components of the snapshot allow you to select from the following options if you need to restore a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    It's always recommended to take a new snapshot before any upgrades.

    Generating the Snapshot from etcd Nodes​

    For each etcd node in the cluster, the etcd cluster health is checked. If the node reports that the etcd cluster is healthy, a snapshot is created from it and optionally uploaded to S3.

    The snapshot is stored in /opt/rke/etcd-snapshots. If the directory is configured on the nodes as a shared mount, it will be overwritten. On S3, the snapshot will always be from the last node that uploads it, as all etcd nodes upload it and the last will remain.

    In the case when multiple etcd nodes exist, any created snapshot is created after the cluster has been health checked, so it can be considered a valid snapshot of the data in the etcd cluster.

    Snapshot Naming Conventions​

    The name of the snapshot is auto-generated. The --name option can be used to override the name of the snapshot when creating one-time snapshots with the RKE CLI.

    When Rancher creates a snapshot of an RKE cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows:

    • m stands for manual
    • r stands for recurring
    • l stands for local
    • s stands for S3

    Some example snapshot names are:

    • c-9dmxz-rl-8b2cx
    • c-9dmxz-ml-kr56m
    • c-9dmxz-ms-t6bjb
    • c-9dmxz-rs-8gxc8

    How Restoring from a Snapshot Works​

    On restore, the following process is used:

    1. The snapshot is retrieved from S3, if S3 is configured.
    2. The snapshot is unzipped (if zipped).
    3. One of the etcd nodes in the cluster serves that snapshot file to the other nodes.
    4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore.
    5. The cluster is restored and post-restore actions will be done in the cluster.

    Configuring Recurring Snapshots

    Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.

    By default, Rancher launched Kubernetes clusters are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the S3 Target or replicating the path on disk is advised.

    During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for Cluster Options. Click on Show advanced options.

    In the Advanced Cluster Options section, there are several options available to configure:

    OptionDescriptionDefault Value
    etcd Snapshot Backup TargetSelect where you want the snapshots to be saved. Options are either local or in S3local
    Recurring etcd Snapshot EnabledEnable/Disable recurring snapshotsYes
    Recurring etcd Snapshot Creation PeriodTime in hours between recurring snapshots12 hours
    Recurring etcd Snapshot Retention CountNumber of snapshots to retain6

    One-Time Snapshots

    In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure.

    1. In the Global view, navigate to the cluster that you want to take a one-time snapshot.

    2. Click the ⋮ > Snapshot Now.

    Result: Based on your snapshot backup target, a one-time snapshot will be taken and saved in the selected backup target.

    Snapshot Backup Targets

    Rancher supports two different backup targets:

    Local Backup Target​

    By default, the local backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the Rancher launched Kubernetes clusters in /opt/rke/etcd-snapshots. All recurring snapshots are taken at configured intervals. The downside of using the local backup target is that if there is a total disaster and all etcd nodes are lost, there is no ability to restore the cluster.

    S3 Backup Target​

    The S3 backup target allows users to configure a S3 compatible backend to store the snapshots. The primary benefit of this option is that if the cluster loses all the etcd nodes, the cluster can still be restored as the snapshots are stored externally. Rancher recommends external targets like S3 backup, however its configuration requirements do require additional effort that should be considered.

    OptionDescriptionRequired
    S3 Bucket NameS3 bucket name where backups will be stored*
    S3 RegionS3 region for the backup bucket
    S3 Region EndpointS3 regions endpoint for the backup bucket*
    S3 Access KeyS3 access key with permission to access the backup bucket*
    S3 Secret KeyS3 secret key with permission to access the backup bucket*
    Custom CA CertificateA custom certificate used to access private S3 backends Available as of v2.2.5

    Using a custom CA certificate for S3​

    Available as of v2.2.5

    The backup snapshot can be stored on a custom S3 backup like minio. If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the Custom CA Certificate option to connect to the S3 backend.

    IAM Support for Storing Snapshots in S3​

    The S3 backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:

    • The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.

    • The cluster etcd nodes must have network access to the specified S3 endpoint.

    • The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket.

    • The Rancher Server worker node(s) must have network access to the specified S3 endpoint.

      To give an application access to S3, refer to the AWS documentation on Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.

    Viewing Available Snapshots

    The list of all available snapshots for the cluster is available in the Rancher UI.

    1. In the Global view, navigate to the cluster that you want to view snapshots.

    2. Click Tools > Snapshots from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.

    Safe Timestamps

    Available as of v2.3.0

    As of v2.2.6, snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable. As of Rancher v2.3.0, the option safe_timestamp is added to support compatible file names. When this flag is set to true, all special characters in the snapshot filename timestamp are replaced.

    This option is not available directly in the UI, and is only available through the Edit as Yaml interface.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html index 99fc147a536..5519ca7d744 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html @@ -5,13 +5,13 @@ Removing Kubernetes Components from Nodes | Rancher Manager - +
    Version: v2.0-v2.4

    Removing Kubernetes Components from Nodes

    This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes.

    When you use Rancher to install Kubernetes on new nodes in an infrastructure provider, resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.

    When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in Active state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again.

    What Gets Removed?​

    When cleaning nodes provisioned using Rancher, the following components are deleted based on the type of cluster node you're removing.

    Removed ComponentNodes Hosted by Infrastructure ProviderCustom NodesHosted ClusterImported Nodes
    The Rancher deployment namespace (cattle-system by default)✓✓✓✓
    serviceAccount, clusterRoles, and clusterRoleBindings labeled by Rancher✓✓✓✓
    Labels, Annotations, and Finalizers✓✓✓✓
    Rancher Deployment✓✓✓
    Machines, clusters, projects, and user custom resource definitions (CRDs)✓✓✓
    All resources create under the management.cattle.io API Group✓✓✓
    All CRDs created by Rancher v2.x✓✓✓

    Removing a Node from a Cluster by Rancher UI​

    When the node is in Active state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    Removing Rancher Components from a Cluster Manually​

    When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components.

    Warning: The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost.

    Removing Rancher Components from Imported Clusters​

    For imported clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions.

    After the imported cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was imported into Rancher.

    Warning: This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost.

    After you initiate the removal of an imported cluster using the Rancher UI (or API), the following events occur.

    1. Rancher creates a serviceAccount that it uses to remove the Rancher components from the cluster. This account is assigned the clusterRole and clusterRoleBinding permissions, which are required to remove the Rancher components.

    2. Using the serviceAccount, Rancher schedules and runs a job that cleans the Rancher components off of the cluster. This job also references the serviceAccount and its roles as dependencies, so the job deletes them before its completion.

    3. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes.

    Result: All components listed for imported clusters in What Gets Removed? are deleted.

    Windows Nodes​

    To clean up a Windows node, you can run a cleanup script located in c:\etc\rancher. The script deletes Kubernetes generated resources and the execution binary. It also drops the firewall rules and network settings.

    To run the script, you can use this command in the PowerShell:

    pushd c:\etc\rancher
    .\cleanup.ps1
    popd

    Result: The node is reset and can be re-added to a Kubernetes cluster.

    Docker Containers, Images, and Volumes​

    Based on what role you assigned to the node, there are Kubernetes components in containers, containers belonging to overlay networking, DNS, ingress controller and Rancher agent. (and pods you created that have been scheduled to this node)

    To clean all Docker containers, images and volumes:

    docker rm -f $(docker ps -qa)
    docker rmi -f $(docker images -q)
    docker volume rm $(docker volume ls -q)

    Mounts​

    Kubernetes components and secrets leave behind mounts on the system that need to be unmounted.

    Mounts
    /var/lib/kubelet/pods/XXX (miscellaneous mounts)
    /var/lib/kubelet
    /var/lib/rancher

    To unmount all mounts:

    for mount in $(mount | grep tmpfs | grep '/var/lib/kubelet' | awk '{ print $3 }') /var/lib/kubelet /var/lib/rancher; do umount $mount; done

    Directories and Files​

    The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using rm -rf /directory_name.

    Note: Depending on the role you assigned to the node, some of the directories will or won't be present on the node.

    Directories
    /etc/ceph
    /etc/cni
    /etc/kubernetes
    /opt/cni
    /opt/rke
    /run/secrets/kubernetes.io
    /run/calico
    /run/flannel
    /var/lib/calico
    /var/lib/etcd
    /var/lib/cni
    /var/lib/kubelet
    /var/lib/rancher/rke/log
    /var/log/containers
    /var/log/kube-audit
    /var/log/pods
    /var/run/calico

    To clean the directories:

    rm -rf /etc/ceph \
           /etc/cni \
           /etc/kubernetes \
           /opt/cni \
           /opt/rke \
           /run/secrets/kubernetes.io \
           /run/calico \
           /run/flannel \
           /var/lib/calico \
           /var/lib/etcd \
           /var/lib/cni \
           /var/lib/kubelet \
           /var/lib/rancher/rke/log \
           /var/log/containers \
           /var/log/kube-audit \
           /var/log/pods \
           /var/run/calico

    Network Interfaces and Iptables​

    The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. To remove these components, a restart is recommended.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    If you want to know more on (virtual) network interfaces or iptables rules, please see the specific subjects below.

    Network Interfaces​

    Note: Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node.

    Interfaces
    flannel.1
    cni0
    tunl0
    caliXXXXXXXXXXX (random interface names)
    vethXXXXXXXX (random interface names)

    To list all interfaces:

    # Using ip
    ip address show

    # Using ifconfig
    ifconfig -a

    To remove an interface:

    ip link delete interface_name

    Iptables​

    Note: Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node.

    Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state.

    Chains
    cali-failsafe-in
    cali-failsafe-out
    cali-fip-dnat
    cali-fip-snat
    cali-from-hep-forward
    cali-from-host-endpoint
    cali-from-wl-dispatch
    cali-fw-caliXXXXXXXXXXX (random chain names)
    cali-nat-outgoing
    cali-pri-kns.NAMESPACE (chain per namespace)
    cali-pro-kns.NAMESPACE (chain per namespace)
    cali-to-hep-forward
    cali-to-host-endpoint
    cali-to-wl-dispatch
    cali-tw-caliXXXXXXXXXXX (random chain names)
    cali-wl-to-host
    KUBE-EXTERNAL-SERVICES
    KUBE-FIREWALL
    KUBE-MARK-DROP
    KUBE-MARK-MASQ
    KUBE-NODEPORTS
    KUBE-SEP-XXXXXXXXXXXXXXXX (random chain names)
    KUBE-SERVICES
    KUBE-SVC-XXXXXXXXXXXXXXXX (random chain names)

    To list all iptables rules:

    iptables -L -t nat
    iptables -L -t mangle
    iptables -L
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html index 37a9b712b39..b8904e43128 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html @@ -5,13 +5,13 @@ Cloning Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Cloning Clusters

    If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster.

    Duplication of imported clusters is not supported.

    Cluster TypeCloneable?
    Nodes Hosted by Infrastructure Provider✓
    Hosted Kubernetes Providers✓
    Custom Cluster✓
    Imported Cluster

    Warning: During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, not wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure.

    Prerequisites​

    Download and install Rancher CLI. Remember to create an API bearer token if necessary.

    1. Export Cluster Config​

    Begin by using Rancher CLI to export the configuration for the cluster that you want to clone.

    1. Open Terminal and change your directory to the location of the Rancher CLI binary, rancher.

    2. Enter the following command to list the clusters managed by Rancher.

        ./rancher cluster ls

    1. Find the cluster that you want to clone, and copy either its resource ID or NAME to your clipboard. From this point on, we'll refer to the resource ID or NAME as <RESOURCE_ID>, which is used as a placeholder in the next step.

    2. Enter the following command to export the configuration for your cluster.

        ./rancher clusters export <RESOURCE_ID>


    **Step Result:** The YAML for a cloned cluster prints to Terminal.
    1. Copy the YAML to your clipboard and paste it in a new file. Save the file as cluster-template.yml (or any other name, as long as it has a .yml extension).

    2. Modify Cluster Config​

    Use your favorite text editor to modify the cluster configuration in cluster-template.yml for your cloned cluster.

    Note: As of Rancher v2.3.0, cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    1. Open cluster-template.yml (or whatever you named your config) in your favorite text editor.

      Warning: Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.

    1. As depicted in the example below, at the <CLUSTER_NAME> placeholder, replace your original cluster's name with a unique name (<CLUSTER_NAME>). If your cloned cluster has a duplicate name, the cluster will not provision successfully.

      Version: v3
      clusters:
          <CLUSTER_NAME>: # ENTER UNIQUE NAME
          dockerRootDir: /var/lib/docker
          enableNetworkPolicy: false
          rancherKubernetesEngineConfig:
          addonJobTimeout: 30
          authentication:
              strategy: x509
          authorization: {}
          bastionHost: {}
          cloudProvider: {}
          ignoreDockerVersion: true

    2. For each nodePools section, replace the original nodepool name with a unique name at the <NODEPOOL_NAME> placeholder. If your cloned cluster has a duplicate nodepool name, the cluster will not provision successfully.

      nodePools:
          <NODEPOOL_NAME>:
          clusterId: do
          controlPlane: true
          etcd: true
          hostnamePrefix: mark-do
          nodeTemplateId: do
          quantity: 1
          worker: true

    3. When you're done, save and close the configuration.

    3. Launch Cloned Cluster​

    Move cluster-template.yml into the same directory as the Rancher CLI binary. Then run this command:

    ./rancher up --file cluster-template.yml

    Result: Your cloned cluster begins provisioning. Enter ./rancher cluster ls to confirm. You can also log into the Rancher UI and open the Global view to watch your provisioning cluster's progress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html index 7dff02a3c39..579d89e204e 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html @@ -5,13 +5,13 @@ GlusterFS Volumes | Rancher Manager - +
    Version: v2.0-v2.4

    GlusterFS Volumes

    This section only applies to RKE clusters.

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. The logging of the kubelet will show: transport endpoint is not connected. To prevent this from happening, you can configure your cluster to mount the systemd-run binary in the kubelet container. There are two requirements before you can change the cluster configuration:

    • The node needs to have the systemd-run binary installed (this can be checked by using the command which systemd-run on each cluster node)
    • The systemd-run binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use)
    docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version

    Note:

    Before updating your Kubernetes YAML to mount the systemd-run binary, make sure the systemd package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.

    services:
      kubelet:
        extra_binds:
          - "/usr/bin/systemd-run:/usr/bin/systemd-run"

    After the cluster has finished provisioning, you can check the kubelet container logging to see if the functionality is activated by looking for the following logline:

    Detected OS with systemd
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html index 61b4d01e367..80fda4d7e1b 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html @@ -5,13 +5,13 @@ How Persistent Storage Works | Rancher Manager - +
    Version: v2.0-v2.4

    How Persistent Storage Works

    A persistent volume (PV) is a piece of storage in the Kubernetes cluster, while a persistent volume claim (PVC) is a request for storage.

    There are two ways to use persistent storage in Kubernetes:

    • Use an existing persistent volume
    • Dynamically provision new persistent volumes

    To use an existing PV, your application will need to use a PVC that is bound to a PV, and the PV should include the minimum resources that the PVC requires.

    For dynamic storage provisioning, your application will need to use a PVC that is bound to a storage class. The storage class contains the authorization to provision new persistent volumes.

    Setting Up New and Existing Persistent Storage

    For more information, refer to the official Kubernetes documentation on storage

    About Persistent Volume Claims​

    Persistent volume claims (PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. A PVC is mounted into a workloads as a volume so that the workload can claim its specified share of the persistent storage.

    To access persistent storage, a pod must have a PVC mounted as a volume. This PVC lets your deployment application store its data in an external location, so that if a pod fails, it can be replaced with a new pod and continue accessing its data stored externally, as though an outage never occurred.

    Each Rancher project contains a list of PVCs that you've created, available from Resources > Workloads > Volumes. (In versions before v2.3.0, the PVCs are in the Volumes tab.) You can reuse these PVCs when creating deployments in the future.

    PVCs are Required for Both New and Existing Persistent Storage​

    A PVC is required for pods to use any persistent storage, regardless of whether the workload is intended to use storage that already exists, or the workload will need to dynamically provision new storage on demand.

    If you are setting up existing storage for a workload, the workload mounts a PVC, which refers to a PV, which corresponds to existing storage infrastructure.

    If a workload should request new storage, the workload mounts PVC, which refers to a storage class, which has the capability to create a new PV along with its underlying storage infrastructure.

    Rancher lets you create as many PVCs within a project as you'd like.

    You can mount PVCs to a deployment as you create it, or later, after the deployment is running.

    Setting up Existing Storage with a PVC and PV​

    Your pods can store data in volumes, but if the pod fails, that data is lost. To solve this issue, Kubernetes offers persistent volumes (PVs), which are Kubernetes resources that correspond to external storage disks or file systems that your pods can access. If a pod crashes, its replacement pod can access the data in persistent storage without any data loss.

    PVs can represent a physical disk or file system that you host on premise, or a vendor-hosted storage resource, such as Amazon EBS or Azure Disk.

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    Important: PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.

    Binding PVs to PVCs​

    When pods are set up to use persistent storage, they mount a persistent volume claim (PVC) that is mounted the same way as any other Kubernetes volume. When each PVC is created, the Kubernetes master considers it to be a request for storage and binds it to a PV that matches the minimum resource requirements of the PVC. Not every PVC is guaranteed to be bound to a PV. According to the Kubernetes documentation,

    Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.

    In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PVs that has at least the amount of disk space required by the PVC.

    To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume.

    Provisioning New Storage with a PVC and Storage Class​

    Storage Classes allow you to create PVs dynamically without having to create persistent storage in an infrastructure provider first.

    For example, if a workload is bound to a PVC and the PVC refers to an Amazon EBS Storage Class, the storage class can dynamically create an EBS volume and a corresponding PV.

    The Kubernetes master will then bind the newly created PV to your workload's PVC, allowing your workload to use the persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html index b4735eb2b2c..7e861624ae2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html @@ -5,13 +5,13 @@ Dynamically Provisioning New Storage in Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    Dynamically Provisioning New Storage in Rancher

    This section describes how to provision new persistent storage for workloads in Rancher.

    This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on how storage works.

    New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster.

    To provision new storage for your workloads, follow these steps:

    1. Add a storage class and configure it to use your storage.
    2. Add a persistent volume claim that refers to the storage class.
    3. Mount the persistent volume claim as a volume for your workload.

    Prerequisites​

    • To set up persistent storage, the Manage Volumes role is required.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.
    • The cloud provider must be enabled. For details on enabling cloud providers, refer to this page.
    • Make sure your storage provisioner is available to be enabled.

    The following storage provisioners are enabled by default:

    NamePlugin
    Amazon EBS Diskaws-ebs
    AzureFileazure-file
    AzureDiskazure-disk
    Google Persistent Diskgce-pd
    Longhornflex-volume-longhorn
    VMware vSphere Volumevsphere-volume
    Locallocal
    Network File Systemnfs
    hostPathhost-path

    To use a storage provisioner that is not on the above list, you will need to use a feature flag to enable unsupported storage drivers.

    1. Add a storage class and configure it to use your storage​

    These steps describe how to set up a storage class at the cluster level.

    1. Go to the cluster for which you want to dynamically provision persistent storage volumes.

    2. From the cluster view, select Storage > Storage Classes. Click Add Class.

    3. Enter a Name for your storage class.

    4. From the Provisioner drop-down, select the service that you want to use to dynamically provision storage volumes. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, use the Amazon EBS Disk provisioner.

    5. From the Parameters section, fill out the information required for the service to dynamically provision storage volumes. Each provisioner requires different information to dynamically provision storage volumes. Consult the service's documentation for help on how to obtain this information.

    6. Click Save.

    Result: The storage class is available to be consumed by a PVC.

    For full information about the storage class parameters, refer to the official Kubernetes documentation..

    2. Add a persistent volume claim that refers to the storage class​

    These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.

    1. Go to the project containing a workload that you want to add a PVC to.

    2. From the main navigation bar, choose Resources > Workloads. (In versions before v2.3.0, choose Workloads on the main navigation bar.) Then select the Volumes tab. Click Add Volume.

    3. Enter a Name for the volume claim.

    4. Select the namespace of the volume claim.

    5. In the Source field, click Use a Storage Class to provision a new persistent volume.

    6. Go to the Storage Class drop-down and select the storage class that you created.

    7. Enter a volume Capacity.

    8. Optional: Expand the Customize section and select the Access Modes that you want to use.

    9. Click Create.

    Result: Your PVC is created. You can now attach it to any workload in the project.

    3. Mount the persistent volume claim as a volume for your workload​

    Mount PVCs to workloads so that your applications can store their data.

    You can mount PVCs during the deployment of a workload, or following workload creation.

    To attach the PVC to a new workload,

    1. Create a workload as you would in Deploying Workloads.
    2. For Workload Type, select Stateful set of 1 pod.
    3. Expand the Volumes section and click Add Volume > Add a New Persistent Volume (Claim).
    4. In the Persistent Volume Claim section, select the newly created persistent volume claim that is attached to the storage class.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Launch.

    Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    To attach the PVC to an existing workload,

    1. Go to the project that has the workload that will have the PVC attached.
    2. Go to the workload that will have persistent storage and click ⋮ > Edit.
    3. Expand the Volumes section and click Add Volume > Add a New Persistent Volume (Claim).
    4. In the Persistent Volume Claim section, select the newly created persistent volume claim that is attached to the storage class.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Save.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. If not, Rancher will provision new persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html index 0089934ce9a..930849ebe92 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html @@ -5,13 +5,13 @@ iSCSI Volumes | Rancher Manager - +
    Version: v2.0-v2.4

    iSCSI Volumes

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes.

    Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the iSCSI initiator tool, which is embedded in the kubelet's rancher/hyperkube Docker image. From each kubelet (i.e., the initiator), the tool discovers and launches sessions with an iSCSI volume (i.e., the target). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure.

    If you encounter this issue, you can work around it by installing the initiator tool on each node in your cluster. You can install the iSCSI initiator tool by logging into your cluster nodes and entering one of the following commands:

    PlatformPackage NameInstall Command
    Ubuntu/Debianopen-iscsisudo apt install open-iscsi
    RHELiscsi-initiator-utilsyum install iscsi-initiator-utils -y

    After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below.

    Note:

    Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the open-iscsi (deb) or iscsi-initiator-utils (yum) package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.

    services:
      kubelet:
        extra_binds:
          - "/etc/iscsi:/etc/iscsi"
          - "/sbin/iscsiadm:/sbin/iscsiadm"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html index b2b37152dbf..c2d13d0394a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html @@ -5,13 +5,13 @@ Setting up Existing Storage | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up Existing Storage

    This section describes how to set up existing persistent storage for workloads in Rancher.

    This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on how storage works.

    To set up storage, follow these steps:

    1. Set up persistent storage.
    2. Add a persistent volume that refers to the persistent storage.
    3. Add a persistent volume claim that refers to the persistent volume.
    4. Mount the persistent volume claim as a volume in your workload.

    Prerequisites​

    • To create a persistent volume as a Kubernetes resource, you must have the Manage Volumes role.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    1. Set up persistent storage​

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using vSphere, NFS, or Amazon's EBS.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster.

    2. Add a persistent volume that refers to the persistent storage​

    These steps describe how to set up a persistent volume at the cluster level in Kubernetes.

    1. From the cluster view, select Storage > Persistent Volumes.

    2. Click Add Volume.

    3. Enter a Name for the persistent volume.

    4. Select the Volume Plugin for the disk type or service that you're using. When adding storage to a cluster that's hosted by a cloud provider, use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the Amazon EBS Disk volume plugin.

    5. Enter the Capacity of your volume in gigabytes.

    6. Complete the Plugin Configuration form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation.

    7. Optional: In the Customize form, configure the access modes. This options sets how many nodes can access the volume, along with the node read/write permissions. The Kubernetes Documentation includes a table that lists which access modes are supported by the plugins available.

    8. Optional: In the Customize form, configure the mount options. Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin's vendor documentation for the mount options available.

    9. Click Save.

    Result: Your new persistent volume is created.

    3. Add a persistent volume claim that refers to the persistent volume​

    These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.

    1. Go to the project containing a workload that you want to add a persistent volume claim to.

    2. Then click the Volumes tab and click Add Volume. (In versions before v2.3.0, click Workloads on the main navigation bar, then Volumes.)

    3. Enter a Name for the volume claim.

    4. Select the namespace of the workload that you want to add the persistent storage to.

    5. In the section called Use an existing persistent volume, go to the Persistent Volume drop-down and choose the persistent volume that you created.

    6. Optional: From Customize, select the Access Modes that you want to use.

    7. Click Create.

    Result: Your PVC is created. You can now attach it to any workload in the project.

    4. Mount the persistent volume claim as a volume in your workload​

    Mount PVCs to stateful workloads so that your applications can store their data.

    You can mount PVCs during the deployment of a workload, or following workload creation.

    The following steps describe how to assign existing storage to a new workload that is a stateful set:

    1. From the Project view, go to the Workloads tab.
    2. Click Deploy.
    3. Enter a name for the workload.
    4. Next to the Workload Type field, click More Options.
    5. Click Stateful set of 1 pod. Optionally, configure the number of pods.
    6. Choose the namespace where the workload will be deployed.
    7. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
    8. In the Persistent Volume Claim field, select the PVC that you created.
    9. In the Mount Point field, enter the path that the workload will use to access the volume.
    10. Click Launch.

    Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    The following steps describe how to assign persistent storage to an existing workload:

    1. From the Project view, go to the Workloads tab.
    2. Go to the workload that you want to add the persistent storage to. The workload type should be a stateful set. Click ⋮ > Edit.
    3. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
    4. In the Persistent Volume Claim field, select the PVC that you created.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Save.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html index 427e07212ff..8b5acc9c505 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html @@ -5,13 +5,13 @@ NFS Storage | Rancher Manager - +
    Version: v2.0-v2.4

    NFS Storage

    Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server.

    Note:

    • If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete adding storage.

    • This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.

    Recommended: To simplify the process of managing firewall rules, use NFSv4.

    1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage.

    2. Enter the following command:

      sudo apt-get install nfs-kernel-server

    3. Enter the command below, which sets the directory used for storage, along with user access rights. Modify the command if you'd like to keep storage at a different directory.

      mkdir -p /nfs && chown nobody:nogroup /nfs
      • The -p /nfs parameter creates a directory named nfs at root.
      • The chown nobody:nogroup /nfs parameter allows all access to the storage directory.

    4. Create an NFS exports table. This table sets the directory paths on your NFS server that are exposed to the nodes that will use the server for storage.

      1. Open /etc/exports using your text editor of choice.

      2. Add the path of the /nfs folder that you created in step 3, along with the IP addresses of your cluster nodes. Add an entry for each IP address in your cluster. Follow each address and its accompanying parameters with a single space that is a delimiter.

        /nfs <IP_ADDRESS1>(rw,sync,no_subtree_check) <IP_ADDRESS2>(rw,sync,no_subtree_check) <IP_ADDRESS3>(rw,sync,no_subtree_check)

        Tip: You can replace the IP addresses with a subnet. For example: 10.212.50.12&#47;24

      3. Update the NFS table by entering the following command:

        exportfs -ra

    5. Open the ports used by NFS.

      1. To find out what ports NFS is using, enter the following command:

        rpcinfo -p | grep nfs

      2. Open the ports that the previous command outputs. For example, the following command opens port 2049:

        sudo ufw allow 2049

    Result: Your NFS server is configured to be used for storage with your Rancher nodes.

    What's Next?​

    Within Rancher, add the NFS server as a storage volume and/or storage class. After adding the server, you can use it for storage for your deployments.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html index 8e04d423795..76141c2b1e7 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html @@ -5,13 +5,13 @@ Creating Persistent Storage in Amazon's EBS | Rancher Manager - +
    Version: v2.0-v2.4

    Creating Persistent Storage in Amazon's EBS

    This section describes how to set up Amazon's Elastic Block Store in EC2.

    1. From the EC2 console, go to the ELASTIC BLOCK STORE section in the left panel and click Volumes.
    2. Click Create Volume.
    3. Optional: Configure the size of the volume or other options. The volume should be created in the same availability zone as the instance it will be attached to.
    4. Click Create Volume.
    5. Click Close.

    Result: Persistent storage has been created.

    For details on how to set up the newly created storage in Rancher, refer to the section on setting up existing storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html index 5740805b828..a1327421fc6 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html @@ -5,13 +5,13 @@ vSphere Storage | Rancher Manager - +
    Version: v2.0-v2.4

    vSphere Storage

    To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a persistent volume claim.

    In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

    Prerequisites​

    In order to provision vSphere volumes in a cluster created with the Rancher Kubernetes Engine (RKE), the vSphere cloud provider must be explicitly enabled in the cluster options.

    Creating a StorageClass​

    Note:

    The following steps can also be performed using the kubectl command line tool. See Kubernetes documentation on persistent volumes for details.

    1. From the Global view, open the cluster where you want to provide vSphere storage.

    2. From the main menu, select Storage > Storage Classes. Then click Add Class.

    3. Enter a Name for the class.

    4. Under Provisioner, select VMWare vSphere Volume.

    5. Optionally, specify additional properties for this storage class under Parameters. Refer to the vSphere storage documentation for details.

    6. Click Save.

    Creating a Workload with a vSphere Volume​

    1. From the cluster where you configured vSphere storage, begin creating a workload as you would in Deploying Workloads.

    2. For Workload Type, select Stateful set of 1 pod.

    3. Expand the Volumes section and click Add Volume.

    4. Choose Add a new persistent volume (claim). This option will implicitly create the claim once you deploy the workload.

    5. Assign a Name for the claim, ie. test-volume and select the vSphere storage class created in the previous step.

    6. Enter the required Capacity for the volume. Then click Define.

    7. Assign a path in the Mount Point field. This is the full path where the volume will be mounted in the container file system, e.g. /persistent.

    8. Click Launch to create the workload.

    Verifying Persistence of the Volume​

    1. From the context menu of the workload you just created, click Execute Shell.

    2. Note the directory at root where the volume has been mounted to (in this case /persistent).

    3. Create a file in the volume by executing the command touch /<volumeMountPoint>/data.txt.

    4. Close the shell window.

    5. Click on the name of the workload to reveal detail information.

    6. Open the context menu next to the Pod in the Running state.

    7. Delete the Pod by selecting Delete.

    8. Observe that the pod is deleted. Then a new pod is scheduled to replace it so that the workload maintains its configured scale of a single stateful pod.

    9. Once the replacement pod is running, click Execute Shell.

    10. Inspect the contents of the directory where the volume is mounted by entering ls -l /<volumeMountPoint>. Note that the file you created earlier is still present.

      workload-persistent-data

    Why to Use StatefulSets Instead of Deployments​

    You should always use StatefulSets for workloads consuming vSphere storage, as this resource type is designed to address a VMDK block storage caveat.

    Since vSphere volumes are backed by VMDK block storage, they only support an access mode of ReadWriteOnce. This setting restricts the volume so that it can only be mounted to a single pod at a time, unless all pods consuming that volume are co-located on the same node. This behavior makes a deployment resource unusable for scaling beyond a single replica if it consumes vSphere volumes.

    Even using a deployment resource with just a single replica may result in a deadlock situation while updating the deployment. If the updated pod is scheduled to a node different from where the existing pod lives, it will fail to start because the VMDK is still attached to the other node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html index d4157ce2a12..52bf44ba9aa 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html @@ -5,7 +5,7 @@ Cluster Autoscaler with AWS EC2 Auto Scaling Groups | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.0-v2.4

    Cluster Autoscaler with AWS EC2 Auto Scaling Groups

    This guide will show you how to install and use Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

    We are going to install a Rancher RKE custom cluster with a fixed number of nodes with the etcd and controlplane roles, and a variable nodes with the worker role, managed by cluster-autoscaler.

    Prerequisites​

    These elements are required to follow this guide:

    • The Rancher server is up and running
    • You have an AWS EC2 user with proper permissions to create virtual machines, auto scaling groups, and IAM profiles and roles

    1. Create a Custom Cluster​

    On Rancher server, we should create a custom k8s cluster v1.18.x. Be sure that cloud_provider name is set to amazonec2. Once cluster is created we need to get:

    • clusterID: c-xxxxx will be used on EC2 kubernetes.io/cluster/<clusterID> instance tag

    • clusterName: will be used on EC2 k8s.io/cluster-autoscaler/<clusterName> instance tag

    • nodeCommand: will be added on EC2 instance user_data to include new nodes on cluster

      sudo docker run -d --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CHECKSUM> <roles>

    2. Configure the Cloud Provider​

    On AWS EC2, we should create a few objects to configure our system. We've defined three distinct groups and IAM profiles to configure on AWS.

    1. Autoscaling group: Nodes that will be part of the EC2 Auto Scaling Group (ASG). The ASG will be used by cluster-autoscaler to scale up and down.

    • IAM profile: Required by k8s nodes where cluster-autoscaler will be running. It is recommended for Kubernetes master nodes. This profile is called K8sAutoscalerProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeAutoScalingInstances",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:SetDesiredCapacity",
                      "autoscaling:TerminateInstanceInAutoScalingGroup",
                      "autoscaling:DescribeTags",
                      "autoscaling:DescribeLaunchConfigurations",
                      "ec2:DescribeLaunchTemplateVersions"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
    1. Master group: Nodes that will be part of the Kubernetes etcd and/or control planes. This will be out of the ASG.

    • IAM profile: Required by the Kubernetes cloud_provider integration. Optionally, AWS_ACCESS_KEY and AWS_SECRET_KEY can be used instead using-aws-credentials. This profile is called K8sMasterProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:DescribeTags",
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ec2:DescribeRouteTables",
                      "ec2:DescribeSecurityGroups",
                      "ec2:DescribeSubnets",
                      "ec2:DescribeVolumes",
                      "ec2:CreateSecurityGroup",
                      "ec2:CreateTags",
                      "ec2:CreateVolume",
                      "ec2:ModifyInstanceAttribute",
                      "ec2:ModifyVolume",
                      "ec2:AttachVolume",
                      "ec2:AuthorizeSecurityGroupIngress",
                      "ec2:CreateRoute",
                      "ec2:DeleteRoute",
                      "ec2:DeleteSecurityGroup",
                      "ec2:DeleteVolume",
                      "ec2:DetachVolume",
                      "ec2:RevokeSecurityGroupIngress",
                      "ec2:DescribeVpcs",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:AttachLoadBalancerToSubnets",
                      "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancerPolicy",
                      "elasticloadbalancing:CreateLoadBalancerListeners",
                      "elasticloadbalancing:ConfigureHealthCheck",
                      "elasticloadbalancing:DeleteLoadBalancer",
                      "elasticloadbalancing:DeleteLoadBalancerListeners",
                      "elasticloadbalancing:DescribeLoadBalancers",
                      "elasticloadbalancing:DescribeLoadBalancerAttributes",
                      "elasticloadbalancing:DetachLoadBalancerFromSubnets",
                      "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
                      "elasticloadbalancing:ModifyLoadBalancerAttributes",
                      "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
                      "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:CreateListener",
                      "elasticloadbalancing:CreateTargetGroup",
                      "elasticloadbalancing:DeleteListener",
                      "elasticloadbalancing:DeleteTargetGroup",
                      "elasticloadbalancing:DescribeListeners",
                      "elasticloadbalancing:DescribeLoadBalancerPolicies",
                      "elasticloadbalancing:DescribeTargetGroups",
                      "elasticloadbalancing:DescribeTargetHealth",
                      "elasticloadbalancing:ModifyListener",
                      "elasticloadbalancing:ModifyTargetGroup",
                      "elasticloadbalancing:RegisterTargets",
                      "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
                      "iam:CreateServiceLinkedRole",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage",
                      "kms:DescribeKey"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }

      • IAM role: K8sMasterRole: [K8sMasterProfile,K8sAutoscalerProfile]

      • Security group: K8sMasterSg More info atRKE ports (custom nodes tab)

      • Tags: kubernetes.io/cluster/<clusterID>: owned

      • User data: K8sMasterUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add etcd+controlplane node to the k8s cluster

        #!/bin/bash -x

        cat <<EOF > /etc/sysctl.d/90-kubelet.conf
        vm.overcommit_memory = 1
        vm.panic_on_oom = 0
        kernel.panic = 10
        kernel.panic_on_oops = 1
        kernel.keys.root_maxkeys = 1000000
        kernel.keys.root_maxbytes = 25000000
        EOF
        sysctl -p /etc/sysctl.d/90-kubelet.conf

        curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
        sudo usermod -aG docker ubuntu

        TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
        PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
        PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
        K8S_ROLES="--etcd --controlplane"

        sudo docker run -d --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}
    1. Worker group: Nodes that will be part of the k8s worker plane. Worker nodes will be scaled by cluster-autoscaler using the ASG.

    • IAM profile: Provides cloud_provider worker integration. This profile is called K8sWorkerProfile.

      ```json
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

    • IAM role: K8sWorkerRole: [K8sWorkerProfile]

    • Security group: K8sWorkerSg More info at RKE ports (custom nodes tab)

    • Tags:

      • kubernetes.io/cluster/<clusterID>: owned
      • k8s.io/cluster-autoscaler/<clusterName>: true
      • k8s.io/cluster-autoscaler/enabled: true

    • User data: K8sWorkerUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add worker node to the k8s cluster

      #!/bin/bash -x

      cat <<EOF > /etc/sysctl.d/90-kubelet.conf
      vm.overcommit_memory = 1
      vm.panic_on_oom = 0
      kernel.panic = 10
      kernel.panic_on_oops = 1
      kernel.keys.root_maxkeys = 1000000
      kernel.keys.root_maxbytes = 25000000
      EOF
      sysctl -p /etc/sysctl.d/90-kubelet.conf

      curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
      sudo usermod -aG docker ubuntu

      TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
      PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
      PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
      K8S_ROLES="--worker"

      sudo docker run -d --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKCSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}

    More info is at RKE clusters on AWS and Cluster Autoscaler on AWS.

    3. Deploy Nodes​

    Once we've configured AWS, let's create VMs to bootstrap our cluster:

    • master (etcd+controlplane): Depending your needs, deploy three master instances with proper size. More info is at the recommendations for production-ready clusters.

      • IAM role: K8sMasterRole
      • Security group: K8sMasterSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
      • User data: K8sMasterUserData

    • worker: Define an ASG on EC2 with the following settings:

      • Name: K8sWorkerAsg
      • IAM role: K8sWorkerRole
      • Security group: K8sWorkerSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
        • k8s.io/cluster-autoscaler/<clusterName>: true
        • k8s.io/cluster-autoscaler/enabled: true
      • User data: K8sWorkerUserData
      • Instances:
        • minimum: 2
        • desired: 2
        • maximum: 10

    Once the VMs are deployed, you should have a Rancher custom cluster up and running with three master and two worker nodes.

    4. Install Cluster-autoscaler​

    At this point, we should have rancher cluster up and running. We are going to install cluster-autoscaler on master nodes and kube-system namespace, following cluster-autoscaler recommendation.

    Parameters​

    This table shows cluster-autoscaler parameters for fine tuning:

    ParameterDefaultDescription
    cluster-name-Autoscaled cluster name, if available
    address:8085The address to expose Prometheus metrics
    kubernetes-Kubernetes master location. Leave blank for default
    kubeconfig-Path to kubeconfig file with authorization and master location information
    cloud-config-The path to the cloud provider configuration file. Empty string for no configuration file
    namespace"kube-system"Namespace in which cluster-autoscaler run
    scale-down-enabledtrueShould CA scale down the cluster
    scale-down-delay-after-add"10m"How long after scale up that scale down evaluation resumes
    scale-down-delay-after-delete0How long after node deletion that scale down evaluation resumes, defaults to scanInterval
    scale-down-delay-after-failure"3m"How long after scale down failure that scale down evaluation resumes
    scale-down-unneeded-time"10m"How long a node should be unneeded before it is eligible for scale down
    scale-down-unready-time"20m"How long an unready node should be unneeded before it is eligible for scale down
    scale-down-utilization-threshold0.5Sum of cpu or memory of all pods running on the node divided by node's corresponding allocatable resource, below which a node can be considered for scale down
    scale-down-gpu-utilization-threshold0.5Sum of gpu requests of all pods running on the node divided by node's allocatable resource, below which a node can be considered for scale down
    scale-down-non-empty-candidates-count30Maximum number of non empty nodes considered in one iteration as candidates for scale down with drain
    scale-down-candidates-pool-ratio0.1A ratio of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    scale-down-candidates-pool-min-count50Minimum number of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    node-deletion-delay-timeout"2m"Maximum time CA waits for removing delay-deletion.cluster-autoscaler.kubernetes.io/ annotations before deleting the node
    scan-interval"10s"How often cluster is reevaluated for scale up or down
    max-nodes-total0Maximum number of nodes in all node groups. Cluster autoscaler will not grow the cluster beyond this number
    cores-total"0:320000"Minimum and maximum number of cores in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    memory-total"0:6400000"Minimum and maximum number of gigabytes of memory in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    cloud-provider-Cloud provider type
    max-bulk-soft-taint-count10Maximum number of nodes that can be tainted/untainted PreferNoSchedule at the same time. Set to 0 to turn off such tainting
    max-bulk-soft-taint-time"3s"Maximum duration of tainting/untainting nodes as PreferNoSchedule at the same time
    max-empty-bulk-delete10Maximum number of empty nodes that can be deleted at the same time
    max-graceful-termination-sec600Maximum number of seconds CA waits for pod termination when trying to scale down a node
    max-total-unready-percentage45Maximum percentage of unready nodes in the cluster. After this is exceeded, CA halts operations
    ok-total-unready-count3Number of allowed unready nodes, irrespective of max-total-unready-percentage
    scale-up-from-zerotrueShould CA scale up when there 0 ready nodes
    max-node-provision-time"15m"Maximum time CA waits for node to be provisioned
    nodes-sets min,max size and other configuration data for a node group in a format accepted by cloud provider. Can be used multiple times. Format: <min>:<max>:<other...>
    node-group-auto-discovery-One or more definition(s) of node group auto-discovery. A definition is expressed <name of discoverer>:[<key>[=<value>]]
    estimator-"binpacking"
    expander"random"Type of node group expander to be used in scale up. Available values: ["random","most-pods","least-waste","price","priority"]
    ignore-daemonsets-utilizationfalseShould CA ignore DaemonSet pods when calculating resource utilization for scaling down
    ignore-mirror-pods-utilizationfalseShould CA ignore Mirror pods when calculating resource utilization for scaling down
    write-status-configmaptrueShould CA write status information to a configmap
    max-inactivity"10m"Maximum time from last recorded autoscaler activity before automatic restart
    max-failing-time"15m"Maximum time from last recorded successful autoscaler run before automatic restart
    balance-similar-node-groupsfalseDetect similar node groups and balance the number of nodes between them
    node-autoprovisioning-enabledfalseShould CA autoprovision node groups when needed
    max-autoprovisioned-node-group-count15The maximum number of autoprovisioned groups in the cluster
    unremovable-node-recheck-timeout"5m"The timeout before we check again a node that couldn't be removed before
    expendable-pods-priority-cutoff-10Pods with priority below cutoff will be expendable. They can be killed without any consideration during scale down and they don't cause scale up. Pods with null priority (PodPriority disabled) are non expendable
    regionalfalseCluster is regional
    new-pod-scale-up-delay"0s"Pods less than this old will not be considered for scale-up
    ignore-taint-Specifies a taint to ignore in node templates when considering to scale a node group
    balancing-ignore-label-Specifies a label to ignore in addition to the basic and cloud-provider set of labels when comparing if two node groups are similar
    aws-use-static-instance-listfalseShould CA fetch instance types in runtime or use a static list. AWS only
    profilingfalseIs debug/pprof endpoint enabled

    Deployment​

    Based on cluster-autoscaler-run-on-master.yaml example, we've created our own cluster-autoscaler-deployment.yaml to use preferred auto-discovery setup, updating tolerations, nodeSelector, image version and command config:

    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
      name: cluster-autoscaler
      namespace: kube-system
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["events", "endpoints"]
        verbs: ["create", "patch"]
      - apiGroups: [""]
        resources: ["pods/eviction"]
        verbs: ["create"]
      - apiGroups: [""]
        resources: ["pods/status"]
        verbs: ["update"]
      - apiGroups: [""]
        resources: ["endpoints"]
        resourceNames: ["cluster-autoscaler"]
        verbs: ["get", "update"]
      - apiGroups: [""]
        resources: ["nodes"]
        verbs: ["watch", "list", "get", "update"]
      - apiGroups: [""]
        resources:
          - "pods"
          - "services"
          - "replicationcontrollers"
          - "persistentvolumeclaims"
          - "persistentvolumes"
        verbs: ["watch", "list", "get"]
      - apiGroups: ["extensions"]
        resources: ["replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["policy"]
        resources: ["poddisruptionbudgets"]
        verbs: ["watch", "list"]
      - apiGroups: ["apps"]
        resources: ["statefulsets", "replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["storage.k8s.io"]
        resources: ["storageclasses", "csinodes"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["batch", "extensions"]
        resources: ["jobs"]
        verbs: ["get", "list", "watch", "patch"]
      - apiGroups: ["coordination.k8s.io"]
        resources: ["leases"]
        verbs: ["create"]
      - apiGroups: ["coordination.k8s.io"]
        resourceNames: ["cluster-autoscaler"]
        resources: ["leases"]
        verbs: ["get", "update"]
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["configmaps"]
        verbs: ["create","list","watch"]
      - apiGroups: [""]
        resources: ["configmaps"]
        resourceNames: ["cluster-autoscaler-status", "cluster-autoscaler-priority-expander"]
        verbs: ["delete", "get", "update", "watch"]

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        app: cluster-autoscaler
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: cluster-autoscaler
      template:
        metadata:
          labels:
            app: cluster-autoscaler
          annotations:
            prometheus.io/scrape: 'true'
            prometheus.io/port: '8085'
        spec:
          serviceAccountName: cluster-autoscaler
          tolerations:
            - effect: NoSchedule
              operator: "Equal"
              value: "true"
              key: node-role.kubernetes.io/controlplane
          nodeSelector:
            node-role.kubernetes.io/controlplane: "true"
          containers:
            - image: eu.gcr.io/k8s-artifacts-prod/autoscaling/cluster-autoscaler:v1.18.1
              name: cluster-autoscaler
              resources:
                limits:
                  cpu: 100m
                  memory: 300Mi
                requests:
                  cpu: 100m
                  memory: 300Mi
              command:
                - ./cluster-autoscaler
                - --v=4
                - --stderrthreshold=info
                - --cloud-provider=aws
                - --skip-nodes-with-local-storage=false
                - --expander=least-waste
                - --node-group-auto-discovery=asg:tag=k8s.io/cluster-autoscaler/enabled,k8s.io/cluster-autoscaler/<clusterName>
              volumeMounts:
                - name: ssl-certs
                  mountPath: /etc/ssl/certs/ca-certificates.crt
                  readOnly: true
              imagePullPolicy: "Always"
          volumes:
            - name: ssl-certs
              hostPath:
                path: "/etc/ssl/certs/ca-certificates.crt"

    Once the manifest file is prepared, deploy it in the Kubernetes cluster (Rancher UI can be used instead):

    kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml

    Note: Cluster-autoscaler deployment can also be set up using manual configuration

    Testing

    At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage K8sWorkerAsg ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true:

    • There are pods that failed to run in the cluster due to insufficient resources. In this case, the cluster is scaled up.
    • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes. In this case, the cluster is scaled down.

    Generating Load​

    We've prepared a test-deployment.yaml just to generate load on the Kubernetes cluster and see if cluster-autoscaler is working properly. The test deployment is requesting 1000m CPU and 1024Mi memory by three replicas. Adjust the requested resources and/or replica to be sure you exhaust the Kubernetes cluster resources:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      labels:
        app: hello-world
      name: hello-world
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: hello-world
      strategy:
        rollingUpdate:
          maxSurge: 1
          maxUnavailable: 0
        type: RollingUpdate
      template:
        metadata:
          labels:
            app: hello-world
        spec:
          containers:
          - image: rancher/hello-world
            imagePullPolicy: Always
            name: hello-world
            ports:
            - containerPort: 80
              protocol: TCP
            resources:
              limits:
                cpu: 1000m
                memory: 1024Mi
              requests:
                cpu: 1000m
                memory: 1024Mi

    Once the test deployment is prepared, deploy it in the Kubernetes cluster default namespace (Rancher UI can be used instead):

    kubectl -n default apply -f test-deployment.yaml

    Checking Scale​

    Once the Kubernetes resources got exhausted, cluster-autoscaler should scale up worker nodes where pods failed to be scheduled. It should scale up until up until all pods became scheduled. You should see the new nodes on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Once scale up is checked, let check for scale down. To do it, reduce the replica number on the test deployment until you release enough Kubernetes cluster resources to scale down. You should see nodes disappear on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html index fdd5f2d53dc..c8efa175ae8 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html @@ -5,13 +5,13 @@ Nodes and Node Pools | Rancher Manager - +
    Version: v2.0-v2.4

    Nodes and Node Pools

    After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's Node tab. Depending on the option used to provision the cluster, there are different node options available.

    If you want to manage the cluster and not individual nodes, see Editing Clusters.

    Node Options Available for Each Cluster Creation Option

    The following table lists which node options are available for each type of cluster in Rancher. Click the links in the Option column for more detailed information about each feature.

    OptionNodes Hosted by an Infrastructure ProviderCustom NodeHosted ClusterImported NodesDescription
    Cordon✓✓✓Marks the node as unschedulable.
    Drain✓✓✓Marks the node as unschedulable and evicts all pods.
    Edit✓✓✓Enter a custom name, description, label, or taints for a node.
    View API✓✓✓View API data.
    Delete✓✓Deletes defective nodes from the cluster.
    Download Keys✓Download SSH key for in order to SSH into the node.
    Node Scaling✓Scale the number of nodes in the node pool up or down.

    Nodes Hosted by an Infrastructure Provider​

    Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are hosted in an infrastructure provider.

    Clusters provisioned using one of the node pool options can be scaled up or down if the node pool is edited.

    A node pool can also automatically maintain the node scale that's set during the initial cluster provisioning if node auto-replace is enabled. This scale determines the number of active nodes that Rancher maintains for the cluster.

    Rancher uses node templates to replace nodes in the node pool. Each node template uses cloud provider credentials to allow Rancher to set up the node in the infrastructure provider.

    Nodes Provisioned by Hosted Kubernetes Providers​

    Options for managing nodes hosted by a Kubernetes provider are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly.

    Imported Nodes​

    Although you can deploy workloads to an imported cluster using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher.

    Managing and Editing Individual Nodes

    Editing a node lets you:

    • Change its name
    • Change its description
    • Add labels
    • Add/Remove taints

    To manage individual nodes, browse to the cluster that you want to manage and then select Nodes from the main menu. You can open the options menu for a node by clicking its ⋮ icon (...).

    Viewing a Node in the Rancher API

    Select this option to view the node's API endpoints.

    Deleting a Node

    Use Delete to remove defective nodes from the cloud provider.

    When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and node auto-replace is enabled.

    Tip: If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, scale down rather than delete.

    Scaling Nodes

    For nodes hosted by an infrastructure provider, you can scale the number of nodes in each node pool by using the scale controls. This option isn't available for other cluster types.

    SSH into a Node Hosted by an Infrastructure Provider

    For nodes hosted by an infrastructure provider, you have the option of downloading its SSH key so that you can connect to it remotely from your desktop.

    1. From the cluster hosted by an infrastructure provider, select Nodes from the main menu.

    2. Find the node that you want to remote into. Select ⋮ > Download Keys.

      Step Result: A ZIP file containing files used for SSH is downloaded.

    3. Extract the ZIP file to any location.

    4. Open Terminal. Change your location to the extracted ZIP file.

    5. Enter the following command:

      ssh -i id_rsa root@<IP_OF_HOST>

    Cordoning a Node

    Cordoning a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.

    Draining a Node

    Draining is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.

    • For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.

    • For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.

    You can drain nodes that are in either a cordoned or active state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods.

    However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value.

    Aggressive and Safe Draining Options​

    The node draining options are different based on your version of Rancher.

    There are two drain modes: aggressive and safe.

    • Aggressive Mode

      In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.

      Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.

    • Safe Mode

      If a node has standalone pods or ephemeral data it will be cordoned but not drained.

    Grace Period​

    The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.

    Timeout​

    The amount of time drain should continue to wait before giving up.

    Kubernetes Known Issue: The timeout setting was not enforced while draining a node before Kubernetes 1.12.

    Drained and Cordoned State​

    If there's any error related to user input, the node enters a cordoned state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.

    If the drain continues without error, the node enters a draining state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to cordoned.

    Once drain successfully completes, the node will be in a state of drained. You can then power off or delete the node.

    Want to know more about cordon and drain? See the Kubernetes documentation.

    Labeling a Node to be Ignored by Rancher

    Available as of 2.3.3

    Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.

    Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.

    In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.

    You can label nodes to be ignored by using a setting in the Rancher UI, or by using kubectl.

    Note: There is an open issue in which nodes labeled to be ignored can get stuck in an updating state.

    Labeling Nodes to be Ignored with the Rancher UI​

    To add a node that is ignored by Rancher,

    1. From the Global view, click the Settings tab.
    2. Go to the ignore-node-name setting and click ⋮ > Edit.
    3. Enter a name that Rancher will use to ignore nodes. All nodes with this name will be ignored.
    4. Click Save.

    Result: Rancher will not wait to register nodes with this name. In the UI, the node will displayed with a grayed-out status. The node is still part of the cluster and can be listed with kubectl.

    If the setting is changed afterward, the ignored nodes will continue to be hidden.

    Labeling Nodes to be Ignored with kubectl​

    To add a node that will be ignored by Rancher, use kubectl to create a node that has the following label:

    cattle.rancher.io/node-status: ignore

    Result: If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with kubectl.

    If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.

    If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.

    If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the nodeName is listed in the Rancher settings under ignore-node-name.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html index 2d78bf3b5c7..b6d0952e9e6 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html @@ -5,13 +5,13 @@ Projects and Kubernetes Namespaces with Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    Projects and Kubernetes Namespaces with Rancher

    A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas.

    A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    This section describes how projects and namespaces work with Rancher. It covers the following topics:

    About Namespaces​

    A namespace is a concept introduced by Kubernetes. According to the official Kubernetes documentation on namespaces,

    Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all.

    Namespaces provide the following functionality:

    • Providing a scope for names: Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace.
    • Resource quotas: Namespaces provide a way to divide cluster resources between multiple users.

    You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace.

    You can assign the following resources directly to namespaces:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    For more information on creating and moving namespaces, see Namespaces.

    Role-based access control issues with namespaces and kubectl​

    Because projects are a concept introduced by Rancher, kubectl does not have the capability to restrict the creation of namespaces to a project the creator has access to.

    This means that when standard users with project-scoped permissions create a namespaces with kubectl, it may be unusable because kubectl doesn't require the new namespace to be scoped within a certain project.

    If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    If a standard user is a project owner, the user will be able to create namespaces within that project. The Rancher UI will prevent that user from creating namespaces outside the scope of the projects they have access to.

    About Projects​

    In terms of hierarchy:

    • Clusters contain projects
    • Projects contain namespaces

    You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    In the base version of Kubernetes, features like role-based access rights or cluster resources are assigned to individual namespaces. A project allows you to save time by giving an individual or a team access to multiple namespaces simultaneously.

    You can use projects to perform actions such as:

    • Assign users to a group of namespaces (i.e., project membership).
    • Assign users specific roles in a project. A role can be owner, member, read-only, or custom.
    • Assign resources to the project.
    • Assign Pod Security Policies.

    When you create a cluster, two projects are automatically created within it:

    The Cluster's Default Project​

    When you provision a cluster with Rancher, it automatically creates a default project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.

    If you don't have a need for more than the default namespace, you also do not need more than the Default project in Rancher.

    If you require another level of organization beyond the Default project, you can create more projects in Rancher to isolate namespaces, applications and resources.

    The System Project​

    Available as of v2.0.7

    When troubleshooting, you can view the system project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers.

    To open it, open the Global menu, and then select the system project for your cluster.

    The system project:

    • Is automatically created when you provision a cluster.
    • Lists all namespaces that exist in v3/settings/system-namespaces, if they exist.
    • Allows you to add more namespaces or move its namespaces to other projects.
    • Cannot be deleted because it's required for cluster operations.

    Note: In clusters where both:

    • The Canal network plug-in is in use.
    • The Project Network Isolation option is enabled.

    The system project overrides the Project Network Isolation option so that it can communicate with other projects, collect logs, and check health.

    Project Authorization​

    Standard users are only authorized for project access in two situations:

    • An administrator, cluster owner or cluster member explicitly adds the standard user to the project's Members tab.
    • Standard users can access projects that they create themselves.

    Pod Security Policies​

    Rancher extends Kubernetes to allow the application of Pod Security Policies at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level.

    Creating Projects​

    This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.

    1. Name a new project.
    2. Optional: Select a pod security policy.
    3. Recommended: Add project members.
    4. Optional: Add resource quotas.

    1. Name a New Project​

    1. From the Global view, choose Clusters from the main menu. From the Clusters page, open the cluster from which you want to create a project.

    2. From the main menu, choose Projects/Namespaces. Then click Add Project.

    3. Enter a Project Name.

    2. Optional: Select a Pod Security Policy​

    This option is only available if you've already created a Pod Security Policy. For instruction, see Creating Pod Security Policies.

    Assigning a PSP to a project will:

    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.

    Use the Members section to provide other users with project access and roles.

    By default, your user is added as the project Owner.

    Notes on Permissions:

    • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Choose Custom to create a custom role on the fly: Custom Project Roles.

    To add members:

    1. Click Add Member.
    2. From the Name combo box, search for a user or group that you want to assign project access. Note: You can only search for groups if external authentication is enabled.
    3. From the Role drop-down, choose a role. For more information, refer to the documentation on project roles.

    4. Optional: Add Resource Quotas​

    Available as of v2.1.0

    Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see Resource Quotas.

    To add a resource quota,

    1. Click Add Quota.
    2. Select a Resource Type. For more information, see Resource Quotas..
    3. Enter values for the Project Limit and the Namespace Default Limit.
    4. Optional: Specify Container Default Resource Limit, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see Container Default Resource Limit Note: This option is available as of v2.2.0.
    5. Click Create.

    Result: Your project is created. You can view it from the cluster's Projects/Namespaces view.

    FieldDescription
    Project LimitThe overall resource limit for the project.
    Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit.

    Switching between Clusters and Projects​

    To switch between clusters and projects, use the Global drop-down available in the main menu.

    Global Menu

    Alternatively, you can switch between projects and clusters using the main menu.

    • To switch between clusters, open the Global view and select Clusters from the main menu. Then open a cluster.
    • To switch between projects, open a cluster, and then select Projects/Namespaces from the main menu. Select the link for the project that you want to open.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/restoring-etcd.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/restoring-etcd.html index cc722c6d71c..2961d7f3c1a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/restoring-etcd.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/restoring-etcd.html @@ -5,13 +5,13 @@ Restoring a Cluster from Backup | Rancher Manager - +
    Version: v2.0-v2.4

    Restoring a Cluster from Backup

    Available as of v2.2.0

    etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed. Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    Rancher recommends enabling the ability to set up recurring snapshots of etcd, but one-time snapshots can easily be taken as well. Rancher allows restore from saved snapshots or if you don't have any snapshots, you can still restore etcd.

    As of Rancher v2.4.0, clusters can also be restored to a prior Kubernetes version and cluster configuration.

    Viewing Available Snapshots​

    The list of all available snapshots for the cluster is available.

    1. In the Global view, navigate to the cluster that you want to view snapshots.

    2. Click Tools > Snapshots from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.

    Restoring a Cluster from a Snapshot​

    If your Kubernetes cluster is broken, you can restore the cluster from a snapshot.

    Restores changed in Rancher v2.4.0.

    Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the cluster.yml. These components allow you to select from the following options when restoring a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    When rolling back to a prior Kubernetes version, the upgrade strategy options are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state.

    Prerequisite: To restore snapshots from S3, the cluster needs to be configured to take recurring snapshots on S3.

    1. In the Global view, navigate to the cluster that you want to restore from a snapshots.

    2. Click the ⋮ > Restore Snapshot.

    3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.

    4. In the Restoration Type field, choose one of the restore options described above.

    5. Click Save.

    Result: The cluster will go into updating state and the process of restoring the etcd nodes from the snapshot will start. The cluster is restored when it returns to an active state.

    Recovering etcd without a Snapshot​

    If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. The cluster should have three etcd nodes to prevent a loss of quorum. If you want to recover your set of etcd nodes, follow these instructions:

    1. Keep only one etcd node in the cluster by removing all other etcd nodes.

    2. On the single remaining etcd node, run the following command:

      $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd

      This command outputs the running command for etcd, save this command to use later.

    3. Stop the etcd container that you launched in the previous step and rename it to etcd-old.

      $ docker stop etcd
      $ docker rename etcd etcd-old

    4. Take the saved command from Step 2 and revise it:

      • If you originally had more than 1 etcd node, then you need to change --initial-cluster to only contain the node that remains.
      • Add --force-new-cluster to the end of the command.

    5. Run the revised command.

    6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a custom cluster and you want to reuse an old node, you are required to clean up the nodes before attempting to add them back into a cluster.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0​

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html index 69fac45cb4f..ae5223ad830 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html @@ -5,13 +5,13 @@ Certificate Rotation | Rancher Manager - +
    Version: v2.0-v2.4

    Certificate Rotation

    Warning: Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window.

    By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted.

    Certificates can be rotated for the following services:

    • etcd
    • kubelet
    • kube-apiserver
    • kube-proxy
    • kube-scheduler
    • kube-controller-manager

    Certificate Rotation in Rancher v2.2.x​

    Available as of v2.2.0

    Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI.

    1. In the Global view, navigate to the cluster that you want to rotate certificates.

    2. Select the ⋮ > Rotate Certificates.

    3. Select which certificates that you want to rotate.

      • Rotate all Service certificates (keep the same CA)
      • Rotate an individual service and choose one of the services from the drop down menu

    4. Click Save.

    Results: The selected certificates will be rotated and the related services will be restarted to start using the new certificate.

    Note: Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher Launched Kubernetes clusters.

    Certificate Rotation in Rancher v2.1.x and v2.0.x​

    Available as of v2.0.14 and v2.1.9

    Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the API.

    1. In the Global view, navigate to the cluster that you want to rotate certificates.

    2. Select the ⋮ > View in API.

    3. Click on RotateCertificates.

    4. Click on Show Request.

    5. Click on Send Request.

    Results: All Kubernetes certificates will be rotated.

    Rotating Expired Certificates After Upgrading Older Rancher Versions​

    If you are upgrading from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your clusters have expired certificates, some manual steps are required to complete the certificate rotation.

    1. For the controlplane and etcd nodes, log in to each corresponding host and check if the certificate kube-apiserver-requestheader-ca.pem is in the following directory:

      cd /etc/kubernetes/.tmp

      If the certificate is not in the directory, perform the following commands:

      cp kube-ca.pem kube-apiserver-requestheader-ca.pem
      cp kube-ca-key.pem kube-apiserver-requestheader-ca-key.pem
      cp kube-apiserver.pem kube-apiserver-proxy-client.pem
      cp kube-apiserver-key.pem kube-apiserver-proxy-client-key.pem

      If the .tmp directory does not exist, you can copy the entire SSL certificate to .tmp:

      cp -r /etc/kubernetes/ssl /etc/kubernetes/.tmp

    2. Rotate the certificates. For Rancher v2.0.x and v2.1.x, use the Rancher API. For Rancher 2.2.x, use the UI.

    3. After the command is finished, check if the worker nodes are Active. If not, log in to each worker node and restart the kubelet and proxy.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html index f356a3e0c77..6d248bf54ff 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html @@ -5,13 +5,13 @@ Adding Users to Projects | Rancher Manager - +
    Version: v2.0-v2.4

    Adding Users to Projects

    If you want to provide a user with access and permissions to specific projects and resources within a cluster, assign the user a project membership.

    You can add members to a project as it is created, or add them to an existing project.

    Tip: Want to provide a user with access to all projects within a cluster? See Adding Cluster Members instead.

    Adding Members to a New Project​

    You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the cluster administration section.

    Adding Members to an Existing Project​

    Following project creation, you can add users as project members so that they can access its resources.

    1. From the Global view, open the project that you want to add members to.

    2. From the main menu, select Members. Then click Add Member.

    3. Search for the user or group that you want to add to the project.

      If external authentication is configured:

      • Rancher returns users from your external authentication source as you type.

      • A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in.

      Note: If you are logged in as a local user, external users do not display in your search results.

    4. Assign the user or group Project roles.

      What are Project Roles?

      Notes:

      • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

      • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

      • For Custom roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the project.

    • To revoke project membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html index ab2ff34c5a0..cc0e8ff6535 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html @@ -5,13 +5,13 @@ Rancher's CI/CD Pipelines | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher's CI/CD Pipelines

    Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

    After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

    • Build your application from code to image.
    • Validate your builds.
    • Deploy your build images to your cluster.
    • Run unit tests.
    • Run regression tests.

    For details, refer to the pipelines section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html index b6bd56b5af8..a1a6ddff805 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html @@ -5,13 +5,13 @@ Namespaces | Rancher Manager - +
    Version: v2.0-v2.4

    Namespaces

    Within Rancher, you can further divide projects into different namespaces, which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the default namespace, you can use multiple namespaces to isolate applications and resources.

    Although you assign resources at the project level so that each namespace in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace.

    Resources that you can assign directly to namespaces include:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    Note: If you create a namespace with kubectl, it may be unusable because kubectl doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    Creating Namespaces​

    Create a new namespace to isolate apps and resources in a project.

    Tip: When working with project resources that you can assign to a namespace (i.e., workloads, certificates, ConfigMaps, etc.) you can create a namespace on the fly.

    1. From the Global view, open the project where you want to create a namespace.

      Tip: As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can create them from the cluster level as well.

    2. From the main menu, select Namespace. The click Add Namespace.

    3. Optional: If your project has Resource Quotas in effect, you can override the default resource Limits (which places a cap on the resources that the namespace can consume).

    4. Enter a Name and then click Create.

    Result: Your namespace is added to the project. You can begin assigning cluster resources to the namespace.

    Moving Namespaces to Another Project​

    Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application.

    1. From the Global view, open the cluster that contains the namespace you want to move.

    2. From the main menu, select Projects/Namespaces.

    3. Select the namespace(s) that you want to move to a different project. Then click Move. You can move multiple namespaces at one.

      Notes:

      • Don't move the namespaces in the System project. Moving these namespaces can adversely affect cluster networking.
      • You cannot move a namespace into a project that already has a resource quota configured.
      • If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace.

    4. Choose a new project for the new namespace and then click Move. Alternatively, you can remove the namespace from all projects by selecting None.

    Result: Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project.

    Editing Namespace Resource Quotas​

    You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    For more information, see how to edit namespace resource quotas.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html index b96fc443ec5..9ff804e2e9b 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html @@ -5,14 +5,14 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.0-v2.4

    Pod Security Policies

    These cluster options are only available for clusters in which Rancher has launched Kubernetes.

    You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.

    Prerequisites​

    Applying a Pod Security Policy​

    1. From the Global view, find the cluster containing the project you want to apply a PSP to.
    2. From the main menu, select Projects/Namespaces.
    3. Find the project that you want to add a PSP to. From that project, select ⋮ > Edit.
    4. From the Pod Security Policy drop-down, select the PSP you want to apply to the project. Assigning a PSP to a project will:
    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.
    1. Click Save.

    Result: The PSP is applied to the project and any namespaces added to the project.

    Note: Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html index 425bb6fa03e..dc2d186c994 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html @@ -5,13 +5,13 @@ How Resource Quotas Work in Rancher Projects | Rancher Manager - +
    Version: v2.0-v2.4

    How Resource Quotas Work in Rancher Projects

    Resource quotas in Rancher include the same functionality as the native version of Kubernetes. However, in Rancher, resource quotas have been extended so that you can apply them to projects.

    In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times.

    In the following diagram, a Kubernetes administrator is trying to enforce a resource quota without Rancher. The administrator wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (Namespace 1-4) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The administrator has to create four different resource quotas that have the same specs configured (Resource Quota 1-4) and apply them individually.

    Base Kubernetes: Unique Resource Quotas Being Applied to Each Namespace

    Native Kubernetes Resource Quota Implementation

    Resource quotas are a little different in Rancher. In Rancher, you apply a resource quota to the project, and then the quota propagates to each namespace, whereafter Kubernetes enforces your limits using the native version of resource quotas. If you want to change the quota for a specific namespace, you can override it.

    The resource quota includes two limits, which you set while creating or editing a project:

    • Project Limits:

      This set of values configures an overall resource limit for the project. If you try to add a new namespace to the project, Rancher uses the limits you've set to validate that the project has enough resources to accommodate the namespace. In other words, if you try to move a namespace into a project near its resource quota, Rancher blocks you from moving the namespace.

    • Namespace Default Limits:

      This value is the default resource limit available for each namespace. When the resource quota is created at the project level, this limit is automatically propagated to each namespace in the project. Each namespace is bound to this default limit unless you override it.

    In the following diagram, a Rancher administrator wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (Namespace 1-4). However, in Rancher, the administrator can set a resource quota for the project (Project Resource Quota) rather than individual namespaces. This quota includes resource limits for both the entire project (Project Limit) and individual namespaces (Namespace Default Limit). Rancher then propagates the Namespace Default Limit quotas to each namespace (Namespace Resource Quota) when created.

    Rancher: Resource Quotas Propagating to Each Namespace

    Rancher Resource Quota Implementation

    Let's highlight some more nuanced functionality. If a quota is deleted at the project level, it will also be removed from all namespaces contained within that project, despite any overrides that may exist. Further, updating an existing namespace default limit for a quota at the project level will not result in that value being propagated to existing namespaces in the project; the updated value will only be applied to newly created namespaces in that project. To update a namespace default limit for existing namespaces you can delete and subsequently recreate the quota at the project level with the new default value. This will result in the new default value being applied to all existing namespaces in the project.

    The following table explains the key differences between the two quota types.

    Rancher Resource QuotasKubernetes Resource Quotas
    Applies to projects and namespace.Applies to namespaces only.
    Creates resource pool for all namespaces in project.Applies static resource limits to individual namespaces.
    Applies resource quotas to namespaces through propagation.Applies only to the assigned namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html index a6fc8d8fa3d..62ab17e5b5a 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html @@ -5,13 +5,13 @@ Overriding the Default Limit for a Namespace | Rancher Manager - +
    Version: v2.0-v2.4

    Overriding the Default Limit for a Namespace

    Although the Namespace Default Limit propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace.

    In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for Namespace 3 so that it has more resources available. Therefore, the administrator raises the namespace limits for Namespace 3 so that the namespace can access more resources.

    Namespace Default Limit Override

    Namespace Default Limit Override

    How to: Editing Namespace Resource Quotas

    Editing Namespace Resource Quotas​

    If there is a resource quota configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    1. From the Global view, open the cluster that contains the namespace for which you want to edit the resource quota.

    2. From the main menu, select Projects/Namespaces.

    3. Find the namespace for which you want to edit the resource quota. Select ⋮ > Edit.

    4. Edit the Resource Quota Limits. These limits determine the resources available to the namespace. The limits must be set within the configured project limits.

      For more information about each Resource Type, see Resource Quotas.

      Note:

      • If a resource quota is not configured for the project, these options will not be available.
      • If you enter limits that exceed the configured project limits, Rancher will not let you save your edits.

    Result: Your override is applied to the namespace's resource quota.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html index bdcdb2328c3..a34015858e2 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html @@ -5,13 +5,13 @@ Resource Quota Type Reference | Rancher Manager - +
    Version: v2.0-v2.4

    Resource Quota Type Reference

    When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types.

    Resource TypeDescription
    CPU Limit*The maximum amount of CPU (in millicores) allocated to the project/namespace.1
    CPU Reservation*The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1
    Memory Limit*The maximum amount of memory (in bytes) allocated to the project/namespace.1
    Memory Reservation*The minimum amount of memory (in bytes) guaranteed to the project/namespace.1
    Storage ReservationThe minimum amount of storage (in gigabytes) guaranteed to the project/namespace.
    Services Load BalancersThe maximum number of load balancers services that can exist in the project/namespace.
    Services Node PortsThe maximum number of node port services that can exist in the project/namespace.
    PodsThe maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of .status.phase in (Failed, Succeeded) equal to true).
    ServicesThe maximum number of services that can exist in the project/namespace.
    ConfigMapsThe maximum number of ConfigMaps that can exist in the project/namespace.
    Persistent Volume ClaimsThe maximum number of persistent volume claims that can exist in the project/namespace.
    Replications ControllersThe maximum number of replication controllers that can exist in the project/namespace.
    SecretsThe maximum number of secrets that can exist in the project/namespace.

    * When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. As of v2.2.0, a container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the Kubernetes documentation for more details on why this is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html index 34f131c13d9..2c61582186b 100644 --- a/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html +++ b/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html @@ -5,13 +5,13 @@ Setting Container Default Resource Limits | Rancher Manager - +
    Version: v2.0-v2.4

    Setting Container Default Resource Limits

    Available as of v2.2.0

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the Kubernetes documentation for more details on why this is required.

    To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    Editing the Container Default Resource Limit​

    Available as of v2.2.0

    Edit container default resource limit when:

    • You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container.
    • You want to edit the default container resource limit.
    1. From the Global view, open the cluster containing the project to which you want to edit the container default resource limit.
    2. From the main menu, select Projects/Namespaces.
    3. Find the project that you want to edit the container default resource limit. From that project, select ⋮ > Edit.
    4. Expand Container Default Resource Limit and edit the values.

    Resource Limit Propagation​

    When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers.

    Note: Before v2.2.0, you could not launch catalog applications that did not have any limits set. With v2.2.0, you can set a default container resource limit on a project and launch any catalog applications.

    Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation.

    Container Resource Quota Types​

    The following resource limits can be configured:

    Resource TypeDescription
    CPU LimitThe maximum amount of CPU (in millicores) allocated to the container.
    CPU ReservationThe minimum amount of CPU (in millicores) guaranteed to the container.
    Memory LimitThe maximum amount of memory (in bytes) allocated to the container.
    Memory ReservationThe minimum amount of memory (in bytes) guaranteed to the container.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html index 263c9f7796b..ac53497b406 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher Installed with Docker | Rancher Manager - +
    Version: v2.0-v2.4

    Backing up Rancher Installed with Docker

    After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.

    How to Read Placeholders​

    During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  \
      --volumes-from rancher-data-<DATE> \
      -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

    In this command, <DATE> is a placeholder for the date that the data container and backup were created. 9-27-18 for example.

    Obtaining Placeholder Data​

    Get the placeholder data by running:

    docker ps

    Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version of Rancher that you're creating a backup for.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped with docker ps -a. Use these commands for help anytime while creating backups.

    Creating a Backup​

    This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>
    3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
      docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
    4. From the data container that you just created (rancher-data-<DATE>), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). Use the following command, replacing each placeholder.
      docker run  --volumes-from rancher-data-<DATE> -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

      Step Result: A stream of commands runs on the screen.

    5. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    6. Move your backup tarball to a safe location external to your Rancher Server. Then delete the rancher-data-<DATE> container from your Rancher Server.

    7. Restart Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker start <RANCHER_CONTAINER_NAME>

    Result: A backup tarball of your Rancher Server data is created. See Restoring Backups: Docker Installs if you need to restore backup data.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-k3s-installed-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-k3s-installed-rancher.html index 15ff760fcc7..4496dc46763 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-k3s-installed-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-k3s-installed-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher Installed on a K3s Kubernetes Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Backing up Rancher Installed on a K3s Kubernetes Cluster

    When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.

    The database administrator will need to back up the external database, or restore it from a snapshot or dump.

    We recommend configuring the database to take recurring snapshots.

    K3s Kubernetes Cluster Data​

    One main advantage of this K3s architecture is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.

    Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

    Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server

    Creating Snapshots and Restoring Databases from Snapshots​

    For details on taking database snapshots and restoring your database from them, refer to the official database documentation:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html index 68240d081d5..f499de03618 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html @@ -5,13 +5,13 @@ Backing up Rancher Installed on an RKE Kubernetes Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Backing up Rancher Installed on an RKE Kubernetes Cluster

    This section describes how to create backups of your high-availability Rancher install.

    In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.

    Cluster Data within an RKE Kubernetes Cluster Running the Rancher Management Server

    Architecture of an RKE Kubernetes cluster running the Rancher management server

    Requirements

    RKE Version​

    The commands for taking etcd snapshots are only available in RKE v0.1.7 and later.

    RKE Config File​

    You'll need the RKE config file that you used for Rancher install, rancher-cluster.yml. You created this file during your initial install. Place this file in same directory as the RKE binary.

    Backup Outline

    Backing up your high-availability Rancher cluster is process that involves completing multiple tasks.

    1. Take Snapshots of the etcd Database

      Take snapshots of your current etcd database using Rancher Kubernetes Engine (RKE).

    2. Store Snapshot(s) Externally

      After taking your snapshots, export them to a safe location that won't be affected if your cluster encounters issues.

    1. Take Snapshots of the etcd Database

    Take snapshots of your etcd database. You can use these snapshots later to recover from a disaster scenario. There are two ways to take snapshots: recurringly, or as a one-off. Each option is better suited to a specific use case. Read the short description below each link to know when to use each option.

    • Option A: Recurring Snapshots

      After you stand up a high-availability Rancher install, we recommend configuring RKE to automatically take recurring snapshots so that you always have a safe restore point available.

    • Option B: One-Time Snapshots

      We advise taking one-time snapshots before events like upgrades or restore of another snapshot.

    Option A: Recurring Snapshots​

    For all high-availability Rancher installs, we recommend taking recurring snapshots so that you always have a safe restore point available.

    To take recurring snapshots, enable the etcd-snapshot service, which is a service that's included with RKE. This service runs in a service container alongside the etcd container. You can enable this service by adding some code to rancher-cluster.yml.

    To Enable Recurring Snapshots:

    The steps to enable recurring snapshots differ based on the version of RKE.

    1. Open rancher-cluster.yml with your favorite text editor.

    2. Edit the code for the etcd service to enable recurring snapshots. Snapshots can be saved in a S3 compatible backend.

      services:
        etcd:
          backup_config:
            enabled: true     # enables recurring etcd snapshots
            interval_hours: 6 # time increment between snapshots
            retention: 60     # time in days before snapshot purge
            # Optional S3
            s3backupconfig:
              access_key: "myaccesskey"
              secret_key:  "myaccesssecret"
              bucket_name: "my-backup-bucket"
              folder: "folder-name" # Available as of v2.3.0
              endpoint: "s3.eu-west-1.amazonaws.com"
              region: "eu-west-1"
              custom_ca: |-
                -----BEGIN CERTIFICATE-----
                $CERTIFICATE
                -----END CERTIFICATE-----

    3. Save and close rancher-cluster.yml.

    4. Open Terminal and change directory to the location of the RKE binary. Your rancher-cluster.yml file must reside in the same directory.

    5. Run the following command:

      rke up --config rancher-cluster.yml

    Result: RKE is configured to take recurring snapshots of etcd on all nodes running the etcd role. Snapshots are saved locally to the following directory: /opt/rke/etcd-snapshots/. If configured, the snapshots are also uploaded to your S3 compatible backend.

    Option B: One-Time Snapshots​

    When you're about to upgrade Rancher or restore it to a previous snapshot, you should snapshot your live image so that you have a backup of etcd in its last known state.

    To Take a One-Time Local Snapshot:

    1. Open Terminal and change directory to the location of the RKE binary. Your rancher-cluster.yml file must reside in the same directory.

    2. Enter the following command. Replace <SNAPSHOT.db> with any name that you want to use for the snapshot (e.g. upgrade.db).

      rke etcd snapshot-save \
      --name <SNAPSHOT.db> \
      --config rancher-cluster.yml

    Result: RKE takes a snapshot of etcd running on each etcd node. The file is saved to /opt/rke/etcd-snapshots.

    To Take a One-Time S3 Snapshot:

    Available as of RKE v0.2.0

    1. Open Terminal and change directory to the location of the RKE binary. Your rancher-cluster.yml file must reside in the same directory.

    2. Enter the following command. Replace <SNAPSHOT.db> with any name that you want to use for the snapshot (e.g. upgrade.db).

      rke etcd snapshot-save \
        --config rancher-cluster.yml \
        --name snapshot-name  \
        --s3 \
        --access-key S3_ACCESS_KEY \
        --secret-key S3_SECRET_KEY \
        --bucket-name s3-bucket-name  \
        --s3-endpoint  s3.amazonaws.com \
        --folder folder-name # Available as of v2.3.0

    Result: RKE takes a snapshot of etcd running on each etcd node. The file is saved to /opt/rke/etcd-snapshots. It is also uploaded to the S3 compatible backend.

    2. Back up Local Snapshots to a Safe Location

    Note: If you are using RKE v0.2.0, you can enable saving the backups to a S3 compatible backend directly and skip this step.

    After taking the etcd snapshots, save them to a safe location so that they're unaffected if your cluster experiences a disaster scenario. This location should be persistent.

    In this documentation, as an example, we're using Amazon S3 as our safe location, and S3cmd as our tool to create the backups. The backup location and tool that you use are ultimately your decision.

    Example:

    root@node:~# s3cmd mb s3://rke-etcd-snapshots
    root@node:~# s3cmd put /opt/rke/etcd-snapshots/snapshot.db s3://rke-etcd-snapshots/
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html index dad9bbb5a44..1e5165a0372 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html @@ -5,13 +5,13 @@ Restoring Backups—Docker Installs | Rancher Manager - +
    Version: v2.0-v2.4

    Restoring Backups—Docker Installs

    If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.

    Before You Start​

    During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
    busybox sh -c "rm /var/lib/rancher/* -rf  && \
    tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"

    In this command, <RANCHER_CONTAINER_NAME> and <RANCHER_VERSION>-<DATE> are environment variables for your Rancher deployment.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version number for your Rancher backup.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

    Restoring Backups​

    Using a backup that you created earlier, restore Rancher to its last known healthy state.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>

    3. Move the backup tarball that you created during completion of Creating Backups—Docker Installs onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

      If you followed the naming convention we suggested in Creating Backups—Docker Installs, it will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    4. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes.

      Warning! This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.

      docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
      busybox sh -c "rm /var/lib/rancher/* -rf  && \
      tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

      Step Result: A series of commands should run.

    5. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data.

      docker start <RANCHER_CONTAINER_NAME>

    6. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-k3s-installed-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-k3s-installed-rancher.html index a66ab17b707..27c81772e6a 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-k3s-installed-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-k3s-installed-rancher.html @@ -5,13 +5,13 @@ Restoring Rancher Installed on a K3s Kubernetes Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Restoring Rancher Installed on a K3s Kubernetes Cluster

    When Rancher is installed on a high-availability Kubernetes cluster, we recommend using an external database to store the cluster data.

    The database administrator will need to back up the external database, or restore it from a snapshot or dump.

    We recommend configuring the database to take recurring snapshots.

    Creating Snapshots and Restoring Databases from Snapshots​

    For details on taking database snapshots and restoring your database from them, refer to the official database documentation:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html index 583b673f10a..e4dbc19ab01 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html @@ -5,14 +5,14 @@ Restoring Backups—Kubernetes installs | Rancher Manager - +
    Version: v2.0-v2.4

    Restoring Backups—Kubernetes installs

    This procedure describes how to use RKE to restore a snapshot of the Rancher Kubernetes cluster. This will restore the Kubernetes configuration and the Rancher database and state.

    Note: This document covers clusters set up with RKE >= v0.2.x, for older RKE versions refer to the RKE Documentation.

    1. Preparation​

    It is advised that you run the restore from your local host or a jump box/bastion where your cluster yaml, rke statefile, and kubeconfig are stored. You will need RKE and kubectl CLI utilities installed locally.

    Prepare by creating 3 new nodes to be the target for the restored Rancher instance. We recommend that you start with fresh nodes and a clean state. For clarification on the requirements, review the Installation Requirements.

    Alternatively you can re-use the existing nodes after clearing Kubernetes and Rancher configurations. This will destroy the data on these nodes. See Node Cleanup for the procedure.

    You must restore each of your etcd nodes to the same snapshot. Copy the snapshot you're using from one of your nodes to the others before running the etcd snapshot-restore command.

    IMPORTANT: Before starting the restore make sure all the Kubernetes services on the old cluster nodes are stopped. We recommend powering off the nodes to be sure.

    2. Place Snapshot​

    As of RKE v0.2.0, snapshots could be saved in an S3 compatible backend. To restore your cluster from the snapshot stored in S3 compatible backend, you can skip this step and retrieve the snapshot in 4. Restore the Database and bring up the Cluster. Otherwise, you will need to place the snapshot directly on one of the etcd nodes.

    Pick one of the clean nodes that will have the etcd role assigned and place the zip-compressed snapshot file in /opt/rke/etcd-snapshots on that node.

    Note: Because of a current limitation in RKE, the restore process does not work correctly if /opt/rke/etcd-snapshots is a NFS share that is mounted on all nodes with the etcd role. The easiest options are to either keep /opt/rke/etcd-snapshots as a local folder during the restore process and only mount the NFS share there after it has been completed, or to only mount the NFS share to one node with an etcd role in the beginning.

    3. Configure RKE​

    Use your original rancher-cluster.yml and rancher-cluster.rkestate files. If they are not stored in a version control system, it is a good idea to back them up before making any changes.

    cp rancher-cluster.yml rancher-cluster.yml.bak
    cp rancher-cluster.rkestate rancher-cluster.rkestate.bak

    If the replaced or cleaned nodes have been configured with new IP addresses, modify the rancher-cluster.yml file to ensure the address and optional internal_address fields reflect the new addresses.

    IMPORTANT: You should not rename the rancher-cluster.yml or rancher-cluster.rkestate files. It is important that the filenames match each other.

    4. Restore the Database and bring up the Cluster​

    You will now use the RKE command-line tool with the rancher-cluster.yml and the rancher-cluster.rkestate configuration files to restore the etcd database and bring up the cluster on the new nodes.

    Note: Ensure your rancher-cluster.rkestate is present in the same directory as the rancher-cluster.yml file before starting the restore, as this file contains the certificate data for the cluster.

    Restoring from a Local Snapshot​

    When restoring etcd from a local snapshot, the snapshot is assumed to be located on the target node in the directory /opt/rke/etcd-snapshots.

    rke etcd snapshot-restore --name snapshot-name --config ./rancher-cluster.yml

    Note: The --name parameter expects the filename of the snapshot without the extension.

    Restoring from a Snapshot in S3​

    Available as of RKE v0.2.0

    When restoring etcd from a snapshot located in an S3 compatible backend, the command needs the S3 information in order to connect to the S3 backend and retrieve the snapshot.

    $ rke etcd snapshot-restore --config ./rancher-cluster.yml --name snapshot-name \
    --s3 --access-key S3_ACCESS_KEY --secret-key S3_SECRET_KEY \
    --bucket-name s3-bucket-name --s3-endpoint s3.amazonaws.com \
    --folder folder-name # Available as of v2.3.0

    Options for rke etcd snapshot-restore​

    S3 specific options are only available for RKE v0.2.0+.

    OptionDescriptionS3 Specific
    --name valueSpecify snapshot name
    --config valueSpecify an alternate cluster YAML file (default: "cluster.yml") [$RKE_CONFIG]
    --s3Enabled backup to s3*
    --s3-endpoint valueSpecify s3 endpoint url (default: "s3.amazonaws.com")*
    --access-key valueSpecify s3 accessKey*
    --secret-key valueSpecify s3 secretKey*
    --bucket-name valueSpecify s3 bucket name*
    --folder valueSpecify s3 folder in the bucket name Available as of v2.3.0*
    --region valueSpecify the s3 bucket location (optional)*
    --ssh-agent-authUse SSH Agent Auth defined by SSH_AUTH_SOCK
    --ignore-docker-versionDisable Docker version check

    Testing the Cluster​

    Once RKE completes it will have created a credentials file in the local directory. Configure kubectl to use the kube_config_rancher-cluster.yml credentials file and check on the state of the cluster. See Installing and Configuring kubectl for details.

    Check Kubernetes Pods​

    Wait for the pods running in kube-system, ingress-nginx and the rancher pod in cattle-system to return to the Running state.

    Note: cattle-cluster-agent and cattle-node-agent pods will be in an Error or CrashLoopBackOff state until Rancher server is up and the DNS/Load Balancer have been pointed at the new cluster.

    kubectl get pods --all-namespaces

    NAMESPACE       NAME                                    READY     STATUS    RESTARTS   AGE
    cattle-system   cattle-cluster-agent-766585f6b-kj88m    0/1       Error     6          4m
    cattle-system   cattle-node-agent-wvhqm                 0/1       Error     8          8m
    cattle-system   rancher-78947c8548-jzlsr                0/1       Running   1          4m
    ingress-nginx   default-http-backend-797c5bc547-f5ztd   1/1       Running   1          4m
    ingress-nginx   nginx-ingress-controller-ljvkf          1/1       Running   1          8m
    kube-system     canal-4pf9v                             3/3       Running   3          8m
    kube-system     cert-manager-6b47fc5fc-jnrl5            1/1       Running   1          4m
    kube-system     kube-dns-7588d5b5f5-kgskt               3/3       Running   3          4m
    kube-system     kube-dns-autoscaler-5db9bbb766-s698d    1/1       Running   1          4m
    kube-system     metrics-server-97bc649d5-6w7zc          1/1       Running   1          4m
    kube-system     tiller-deploy-56c4cf647b-j4whh          1/1       Running   1          4m

    Finishing Up​

    Rancher should now be running and available to manage your Kubernetes clusters.

    IMPORTANT: Remember to save your updated RKE config (rancher-cluster.yml) state file (rancher-cluster.rkestate) and kubectl credentials (kube_config_rancher-cluster.yml) files in a safe place for future maintenance for example in a version control system.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.html b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.html index 40a7eb5d660..a27e8c225f8 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup/roll-back-to-v2.0-v2.1.html @@ -5,13 +5,13 @@ Rolling back to v2.0.0-v2.1.5 | Rancher Manager - +
    Version: v2.0-v2.4

    Rolling back to v2.0.0-v2.1.5

    Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved here and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible.

    If you are rolling back to versions in either of these scenarios, you must follow some extra instructions in order to get your clusters working.

    • Rolling back from v2.1.6+ to any version between v2.1.0 - v2.1.5 or v2.0.0 - v2.0.10.
    • Rolling back from v2.0.11+ to any version between v2.0.0 - v2.0.10.

    Because of the changes necessary to address CVE-2018-20321, special steps are necessary if the user wants to roll back to a previous version of Rancher where this vulnerability exists. The steps are as follows:

    1. Record the serviceAccountToken for each cluster. To do this, save the following script on a machine with kubectl access to the Rancher management plane and execute it. You will need to run these commands on the machine where the rancher container is running. Ensure JQ is installed before running the command. The commands will vary depending on how you installed Rancher.

      Rancher Installed with Docker

      docker exec <NAME OF RANCHER CONTAINER> kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json

      Rancher Installed on a Kubernetes Cluster

      kubectl get clusters -o json | jq '[.items[] | select(any(.status.conditions[]; .type == "ServiceAccountMigrated")) | {name: .metadata.name, token: .status.serviceAccountToken}]' > tokens.json

    2. After executing the command a tokens.json file will be created. Important! Back up this file in a safe place. You will need it to restore functionality to your clusters after rolling back Rancher. If you lose this file, you may lose access to your clusters.**

    3. Rollback Rancher following the normal instructions.

    4. Once Rancher comes back up, every cluster managed by Rancher (except for Imported clusters) will be in an Unavailable state.

    5. Apply the backed up tokens based on how you installed Rancher.

      Rancher Installed with Docker

      Save the following script as apply_tokens.sh to the machine where the Rancher docker container is running. Also copy the tokens.json file created previously to the same directory as the script.

      set -e

      tokens=$(jq .[] -c tokens.json)
      for token in $tokens; do
          name=$(echo $token | jq -r .name)
          value=$(echo $token | jq -r .token)

          docker exec $1 kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
      done

      the script to allow execution (chmod +x apply_tokens.sh) and execute the script as follows:

      ./apply_tokens.sh <DOCKER CONTAINER NAME>

      After a few moments the clusters will go from Unavailable back to Available.

      Rancher Installed on a Kubernetes Cluster

      Save the following script as apply_tokens.sh to a machine with kubectl access to the Rancher management plane. Also copy the tokens.json file created previously to the same directory as the script.

      set -e

      tokens=$(jq .[] -c tokens.json)
      for token in $tokens; do
          name=$(echo $token | jq -r .name)
          value=$(echo $token | jq -r .token)

         kubectl patch --type=merge clusters $name -p "{\"status\": {\"serviceAccountToken\": \"$value\"}}"
      done

      Set the script to allow execution (chmod +x apply_tokens.sh) and execute the script as follows:

      ./apply_tokens.sh

      After a few moments the clusters will go from Unavailable back to Available.

    6. Continue using Rancher as normal.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.html b/v2.0-v2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.html index 7f25a68bbe6..635f2a1d261 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/deploy-apps-across-clusters.html @@ -5,14 +5,14 @@ Deploying Applications across Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Deploying Applications across Clusters

    Available as of v2.2.0

    Typically, most applications are deployed on a single Kubernetes cluster, but there will be times you might want to deploy multiple copies of the same application across different clusters and/or projects. In Rancher, a multi-cluster application, is an application deployed using a Helm chart across multiple clusters. With the ability to deploy the same application across multiple clusters, it avoids the repetition of the same action on each cluster, which could introduce user error during application configuration. With multi-cluster applications, you can customize to have the same configuration across all projects/clusters as well as have the ability to change the configuration based on your target project. Since multi-cluster application is considered a single application, it's easy to manage and maintain this application.

    Any Helm charts from a global catalog can be used to deploy and manage multi-cluster applications.

    After creating a multi-cluster application, you can program a Global DNS entry to make it easier to access the application.

    Prerequisites

    To create a multi-cluster app in Rancher, you must have at least one of the following permissions:

    • A project-member role in the target cluster(s), which gives you the ability to create, read, update, and delete the workloads
    • A cluster owner role for the clusters(s) that include the target project(s)

    Launching a Multi-Cluster App

    1. From the Global view, choose Apps in the navigation bar. Click Launch.

    2. Find the application that you want to launch, and then click View Details.

    3. (Optional) Review the detailed descriptions, which are derived from the Helm chart's README.

    4. Under Configuration Options enter a Name for the multi-cluster application. By default, this name is also used to create a Kubernetes namespace in each target project for the multi-cluster application. The namespace is named as <MULTI-CLUSTER_APPLICATION_NAME>-<PROJECT_ID>.

    5. Select a Template Version.

    6. Complete the multi-cluster applications specific configuration options as well as the application configuration options.

    7. Select the Members who can interact with the multi-cluster application.

    8. Add any custom application configuration answers that would change the configuration for specific project(s) from the default application configuration answers.

    9. Review the files in the Preview section. When you're satisfied, click Launch.

    Result: Your application is deployed to your chosen namespace. You can view the application status from the project's:

    Multi-cluster App Configuration Options

    Rancher has divided the configuration option for the multi-cluster application into several sections.

    Targets​

    In the Targets section, select the projects that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on -.

    Upgrades​

    In the Upgrades section, select the upgrade strategy to use, when you decide to upgrade your application.

    • Rolling Update (batched): When selecting this upgrade strategy, the number of applications upgraded at a time is based on the selected Batch size and the Interval specifies how many seconds to wait before starting the next batch of updates.

    • Upgrade all apps simultaneously: When selecting this upgrade strategy, all applications across all projects will be upgraded at the same time.

    Roles​

    In the Roles section, you define the role of the multi-cluster application. Typically, when a user launches catalog applications, that specific user's permissions are used for creation of all workloads/resources that is required by the app.

    For multi-cluster applications, the application is deployed by a system user and is assigned as the creator of all underlying resources. A system user is used instead of the actual user due to the fact that the actual user could be removed from one of the target projects. If the actual user was removed from one of the projects, then that user would no longer be able to manage the application for the other projects.

    Rancher will let you select from two options for Roles, Project and Cluster. Rancher will allow creation using any of these roles based on the user's permissions.

    • Project - This is the equivalent of a project member. If you select this role, Rancher will check that in all the target projects, the user has minimally the project member role. While the user might not be explicitly granted the project member role, if the user is an administrator, a cluster owner, or a project owner, then the user is considered to have the appropriate level of permissions.

    • Cluster - This is the equivalent of a cluster owner. If you select this role, Rancher will check that in all the target projects, the user has minimally the cluster owner role. While the user might not be explicitly granted the cluster owner role, if the user is an administrator, then the user is considered to have the appropriate level of permissions.

    When launching the application, Rancher will confirm if you have these permissions in the target projects before launching the application.

    Note: There are some applications like Grafana or Datadog that require access to specific cluster-scoped resources. These applications will require the Cluster role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles.

    Application Configuration Options

    For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in Using Helm: The format and limitations of –set, as Rancher passes them as --set flags to Helm.

    For example, when entering an answer that includes two values separated by a comma (i.e. abc, bcd), it is required to wrap the values with double quotes (i.e., "abc, bcd").

    Using a questions.yml file​

    If the Helm chart that you are deploying contains a questions.yml file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.

    Key Value Pairs for Native Helm Charts​

    For native Helm charts (i.e., charts from the Helm Stable or Helm Incubator catalogs or a custom Helm chart repository, answers are provided as key value pairs in the Answers section. These answers are used to override the default values.

    Members​

    By default, multi-cluster applications can only be managed by the user who created it. In the Members section, other users can be added so that they can also help manage or view the multi-cluster application.

    1. Find the user that you want to add by typing in the member's name in the Member search box.

    2. Select the Access Type for that member. There are three access types for a multi-cluster project, but due to how the permissions of a multi-cluster application are launched, please read carefully to understand what these access types mean.

      • Owner: This access type can manage any configuration part of the multi-cluster application including the template version, the [multi-cluster applications specific configuration options](#Multi-cluster App Configuration Options), the application specific configuration options, the members who can interact with the multi-cluster application and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any owner of the multi-cluster application can manage/remove applications in target projects without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Member: This access type can only modify the template version, the application specific configuration options and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any member of the multi-cluster application can modify the application without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Read-only: This access type cannot modify any configuration option for the multi-cluster application. Users can only view these applications.

      Note: Please ensure only trusted users are given Owner or Member access as they will automatically be able to manage applications created for this multi-cluster application in target projects they might not have direct access to.

    Overriding Application Configuration Options for Specific Projects​

    The ability to use the same configuration to deploy the same application across multiple clusters/projects is one of the main benefits of multi-cluster applications. There might be a specific project that requires a slightly different configuration option, but you want to manage that application with all the other matching applications. Instead of creating a brand new application, you can override specific application specific configuration options for specific projects.

    1. In the Answer Overrides section, click Add Override.

    2. For each override, you can select the following:

      • Scope: Select which target projects you want to override the answer in the configuration option.

      • Question: Select which question you want to override.

      • Answer: Enter the answer that you want to be used instead.

    Upgrading Multi-Cluster App Roles and Projects

    • Changing Roles on an existing Multi-Cluster app The creator and any users added with the access-type "owner" to a multi-cluster app, can upgrade its Roles. When adding a new Role, we check if the user has that exact role in all current target projects. These checks allow the same relaxations for global admins, cluster owners and project-owners as described in the installation section for the field Roles.

    • Adding/Removing target projects

    1. The creator and any users added with access-type "owner" to a multi-cluster app, can add or remove its target projects. When adding a new project, we check if the caller of this request has all Roles defined on multi-cluster app, in the new projects they want to add. The roles checks are again relaxed for global admins, cluster-owners and project-owners.
    2. We do not do these membership checks when removing target projects. This is because the caller's permissions could have with respect to the target project, or the project could have been deleted and hence the caller wants to remove it from targets list.

    Multi-Cluster Application Management

    One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back.

    1. From the Global view, choose Apps in the navigation bar.

    2. Choose the multi-cluster application you want to take one of these actions on and click the ⋮. Select one of the following options:

      • Clone: Creates another multi-cluster application with the same configuration. By using this option, you can easily duplicate a multi-cluster application.
      • Upgrade: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the upgrade strategy can be modified if you have the correct access type.
      • Rollback: Rollback your application to a specific version. If after an upgrade, there are issues for your multi-cluster application for one or more of your targets, Rancher has stored up to 10 versions of the multi-cluster application. Rolling back a multi-cluster application reverts the application for all target clusters and projects, not just the targets(s) affected by the upgrade issue.

    Deleting a Multi-Cluster Application

    1. From the Global view, choose Apps in the navigation bar.

    2. Choose the multi-cluster application you want to delete and click the ⋮ > Delete. When deleting the multi-cluster application, all applications and namespaces are deleted in all of the target projects.

      Note: The applications in the target projects, that are created for a multi-cluster application, cannot be deleted individually. The applications can only be deleted when the multi-cluster application is deleted.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.html index 72795c94ece..48793ed7e1e 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/adding-catalogs.html @@ -5,13 +5,13 @@ Creating Custom Catalogs | Rancher Manager - +
    Version: v2.0-v2.4

    Creating Custom Catalogs

    Custom catalogs can be added into Rancher at a global scope, cluster scope, or project scope.

    Adding Catalog Repositories

    Adding a catalog is as simple as adding a catalog name, a URL and a branch name.

    Prerequisite: An admin of Rancher has the ability to add or remove catalogs globally in Rancher.

    Add Custom Git Repositories​

    The Git URL needs to be one that git clone can handle and must end in .git. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the master branch by default. Whenever you add a catalog to Rancher, it will be available immediately.

    Add Custom Helm Chart Repositories​

    A Helm chart repository is an HTTP server that houses one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.

    Helm comes with built-in package server for developer testing (helm serve). The Helm team has tested other servers, including Google Cloud Storage with website mode enabled, S3 with website mode enabled or hosting custom chart repository server using open-source projects like ChartMuseum.

    In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.

    Add Private Git/Helm Chart Repositories​

    Available as of v2.2.0

    Private catalog repositories can be added using credentials like Username and Password. You may also want to use the OAuth token if your Git or Helm repository server supports that.

    For more information on private Git/Helm catalogs, refer to the custom catalog configuration reference.

    1. From the Global view, choose Tools > Catalogs in the navigation bar. In versions before v2.2.0, you can select Catalogs directly in the navigation bar.

    2. Click Add Catalog.

    3. Complete the form and click Create.

      Result: Your catalog is added to Rancher.

    Adding Global Catalogs

    Prerequisites: In order to manage the built-in catalogs or manage global catalogs, you need one of the following permissions:

    1. From the Global view, choose Tools > Catalogs in the navigation bar. In versions before v2.2.0, you can select Catalogs directly in the navigation bar.

    2. Click Add Catalog.

    3. Complete the form. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to this section.

    4. Click Create.

      Result: Your custom global catalog is added to Rancher. Once it is in Active state, it has completed synchronization and you will be able to start deploying multi-cluster apps or applications in any project from this catalog.

    Adding Cluster Level Catalogs

    Available as of v2.2.0

    Prerequisites: In order to manage cluster scoped catalogs, you need one of the following permissions:

    1. From the Global view, navigate to your cluster that you want to start adding custom catalogs.
    2. Choose the Tools > Catalogs in the navigation bar.
    3. Click Add Catalog.
    4. Complete the form. By default, the form will provide the ability to select Scope of the catalog. When you have added a catalog from the Cluster scope, it is defaulted to Cluster. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to this section.
    5. Click Create.

    Result: Your custom cluster catalog is added to Rancher. Once it is in Active state, it has completed synchronization and you will be able to start deploying applications in any project in that cluster from this catalog.

    Adding Project Level Catalogs

    Available as of v2.2.0

    Prerequisites: In order to manage project scoped catalogs, you need one of the following permissions:

    1. From the Global view, navigate to your project that you want to start adding custom catalogs.
    2. Choose the Tools > Catalogs in the navigation bar.
    3. Click Add Catalog.
    4. Complete the form. By default, the form will provide the ability to select Scope of the catalog. When you have added a catalog from the Project scope, it is defaulted to Cluster. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to this section.
    5. Click Create.

    Result: Your custom project catalog is added to Rancher. Once it is in Active state, it has completed synchronization and you will be able to start deploying applications in that project from this catalog.

    Custom Catalog Configuration Reference

    Refer to this page more information on configuring custom catalogs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/built-in.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/built-in.html index ffb2f3f08e6..39adf26f823 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/built-in.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/built-in.html @@ -5,13 +5,13 @@ Enabling and Disabling Built-in Global Catalogs | Rancher Manager - +
    Version: v2.0-v2.4

    Enabling and Disabling Built-in Global Catalogs

    There are default global catalogs packaged as part of Rancher.

    Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.

    Prerequisites: In order to manage the built-in catalogs or manage global catalogs, you need one of the following permissions:

    1. From the Global view, choose Tools > Catalogs in the navigation bar. In versions before v2.2.0, you can select Catalogs directly in the navigation bar.

    2. Toggle the default catalogs that you want to be enabled or disabled:

      • Library: The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. This catalog features Rancher Charts, which include some notable advantages over native Helm charts.
      • Helm Stable: This catalog, which is maintained by the Kubernetes community, includes native Helm charts. This catalog features the largest pool of apps.
      • Helm Incubator: Similar in user experience to Helm Stable, but this catalog is filled with applications in beta.

      Result: The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting Apps from the main navigation bar. In versions before v2.2.0, within a project, you can select Catalog Apps from the main navigation bar.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.html index ee560b27fbb..94579879deb 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/catalog-config.html @@ -5,14 +5,14 @@ Custom Catalog Configuration Reference | Rancher Manager - +
    Version: v2.0-v2.4

    Custom Catalog Configuration Reference

    Any user can create custom catalogs to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.

    Types of Repositories

    Rancher supports adding in different types of repositories as a catalog:

    • Custom Git Repository
    • Custom Helm Chart Repository

    Custom Git Repository

    The Git URL needs to be one that git clone can handle and must end in .git. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will default to use the master branch. Whenever you add a catalog to Rancher, it will be available almost immediately.

    Custom Helm Chart Repository

    A Helm chart repository is an HTTP server that contains one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.

    Helm comes with a built-in package server for developer testing (helm serve). The Helm team has tested other servers, including Google Cloud Storage with website mode enabled, S3 with website mode enabled or hosting custom chart repository server using open-source projects like ChartMuseum.

    In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.

    Catalog Fields

    When adding your catalog to Rancher, you'll provide the following information:

    VariableDescription
    NameName for your custom catalog to distinguish the repositories in Rancher
    Catalog URLURL of your custom chart repository
    Use Private CatalogSelected if you are using a private repository that requires authentication
    Username (Optional)Username or OAuth Token
    Password (Optional)If you are authenticating using a username, enter the associated password. If you are using an OAuth token, use x-oauth-basic.
    BranchFor a Git repository, the branch name. Default: master. For a Helm Chart repository, this field is ignored.
    Helm versionThe Helm version that will be used to deploy all of the charts in the catalog. This field cannot be changed later. For more information, refer to the section on Helm versions.

    Private Repositories

    Available as of v2.2.0

    Private Git or Helm chart repositories can be added into Rancher using either credentials, i.e. Username and Password. Private Git repositories also support authentication using OAuth tokens.

    Using Username and Password​

    1. When adding the catalog, select the Use private catalog checkbox.

    2. Provide the Username and Password for your Git or Helm repository.

    Using an OAuth token​

    Read using Git over HTTPS and OAuth for more details on how OAuth authentication works.

    1. Create an OAuth token with repo permission selected, and click Generate token.

    2. When adding the catalog, select the Use private catalog checkbox.

    3. For Username, provide the Git generated OAuth token. For Password, enter x-oauth-basic.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.html index aae2e8bbaf7..d9da3f94cf0 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps.html @@ -5,13 +5,13 @@ Creating Catalog Apps | Rancher Manager - +
    Version: v2.0-v2.4

    Creating Catalog Apps

    Rancher's catalog service requires any custom catalogs to be structured in a specific format for the catalog service to be able to leverage it in Rancher.

    For a complete walkthrough of developing charts, see the Chart Template Developer's Guide in the official Helm documentation.

    Chart Types

    Rancher supports two different types of charts: Helm charts and Rancher charts.

    Helm Charts​

    Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you'll learn the chart's parameters and then configure them using Answers, which are sets of key value pairs.

    The Helm Stable and Helm Incubators are populated with native Helm charts. However, you can also use native Helm charts in Custom catalogs (although we recommend Rancher Charts).

    Rancher Charts​

    Rancher charts mirror native helm charts, although they add two files that enhance user experience: app-readme.md and questions.yaml. Read more about them in Additional Files for Rancher Charts.

    Advantages of Rancher charts include:

    • Enhanced revision tracking: While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart.
    • Streamlined application launch: Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application.
    • Application resource management: Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application.

    Chart Directory Structure

    The following table demonstrates the directory structure for a Rancher Chart. The charts directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. This information is helpful when customizing charts for a custom catalog. The questions.yaml, README.md, and requirements.yml files are specific to Rancher charts, but are optional for chart customization.

    <Repository-Base>/
     │
     ├── charts/
     │   ├── <Application Name>/      # This directory name will be surfaced in the Rancher UI as the chart name
     │   │   ├── <App Version>/   # Each directory at this level provides different app versions that will be selectable within the chart in the Rancher UI
     │   │   │   ├── Chart.yaml   # Required Helm chart information file.
     │   │   │   ├── questions.yaml   # Form questions displayed within the Rancher UI. Questions display in Configuration Options.*
     │   │   │   ├── README.md         # Optional: Helm Readme file displayed within Rancher UI. This text displays in Detailed Descriptions.
     │   │   │   ├── requirements.yml  # Optional: YAML file listing dependencies for the chart.
     │   │   │   ├── values.yml        # Default configuration values for the chart.
     │   │   │   ├── templates/        # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML.

    Additional Files for Rancher Charts

    Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from Helm charts in their directory structures. Rancher charts include two files that Helm charts do not.

    • app-readme.md

      A file that provides descriptive text in the chart's UI header. The following image displays the difference between a Rancher chart (which includes app-readme.md) and a native Helm chart (which does not).

      Rancher Chart with app-readme.md (left) vs. Helm Chart without (right)

      app-readme.md

    • questions.yml

      A file that contains questions for a form. These form questions simplify deployment of a chart. Without it, you must configure the deployment using key value pairs, which is more difficult. The following image displays the difference between a Rancher chart (which includes questions.yml) and a native Helm chart (which does not).

    <figcaption>Rancher Chart with <code>questions.yml</code> (left) vs. Helm Chart without (right)</figcaption>

    ![questions.yml](/img/questions.png)

    questions.yml​

    Inside the questions.yml, most of the content will be around the questions to ask the end user, but there are some additional fields that can be set in this file.

    Min/Max Rancher versions​

    Available as of v2.3.0

    For each chart, you can add the minimum and/or maximum Rancher version, which determines whether or not this chart is available to be deployed from Rancher.

    Note: Even though Rancher release versions are prefixed with a v, there is no prefix for the release version when using this option.

    rancher_min_version: 2.3.0
    rancher_max_version: 2.3.99

    Question Variable Reference​

    This reference contains variables that you can use in questions.yml nested under questions:.

    VariableTypeRequiredDescription
    variablestringtrueDefine the variable name specified in the values.yml file, using foo.bar for nested objects.
    labelstringtrueDefine the UI label.
    descriptionstringfalseSpecify the description of the variable.
    typestringfalseDefault to string if not specified (current supported types are string, multiline, boolean, int, enum, password, storageclass, hostname, pvc, and secret).
    requiredboolfalseDefine if the variable is required or not (true | false)
    defaultstringfalseSpecify the default value.
    groupstringfalseGroup questions by input value.
    min_lengthintfalseMin character length.
    max_lengthintfalseMax character length.
    minintfalseMin integer length.
    maxintfalseMax integer length.
    options[]stringfalseSpecify the options when the variable type is enum, for example: options:
    - "ClusterIP"
    - "NodePort"
    - "LoadBalancer"
    valid_charsstringfalseRegular expression for input chars validation.
    invalid_charsstringfalseRegular expression for invalid input chars validation.
    subquestions[]subquestionfalseAdd an array of subquestions.
    show_ifstringfalseShow current variable if conditional variable is true. For example show_if: "serviceType=Nodeport"
    show_subquestion_ifstringfalseShow subquestions if is true or equal to one of the options. for example show_subquestion_if: "true"

    Note: subquestions[] cannot contain subquestions or show_subquestions_if keys, but all other keys in the above table are supported.

    Tutorial: Example Custom Chart Creation

    For a tutorial on adding a custom Helm chart to a custom catalog, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.html index e5334ffad4f..ae69ecf108e 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/globaldns.html @@ -5,13 +5,13 @@ Global DNS | Rancher Manager - +
    Version: v2.0-v2.4

    Global DNS

    Available as of v2.2.0

    Rancher's Global DNS feature provides a way to program an external DNS provider to route traffic to your Kubernetes applications. Since the DNS programming supports spanning applications across different Kubernetes clusters, Global DNS is configured at a global level. An application can become highly available as it allows you to have one application run on different Kubernetes clusters. If one of your Kubernetes clusters goes down, the application would still be accessible.

    Note: Global DNS is only available in Kubernetes installations with the local cluster enabled.

    Global DNS Providers

    Before adding in Global DNS entries, you will need to configure access to an external provider.

    The following table lists the first version of Rancher each provider debuted.

    DNS ProviderAvailable as of
    AWS Route53v2.2.0
    CloudFlarev2.2.0
    AliDNSv2.2.0

    Global DNS Entries

    For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single multi-cluster application or to specific projects. You must add specific annotation labels to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work.

    Permissions for Global DNS Providers and Entries

    By default, only global administrators and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get Owner role to manage them.

    Setting up Global DNS for Applications

    1. From the Global View, select Tools > Global DNS Providers.
    2. To add a provider, choose from the available provider options and configure the Global DNS Provider with necessary credentials and an optional domain. For help, see DNS Provider Configuration.
    3. (Optional) Add additional users so they could use the provider when creating Global DNS entries as well as manage the Global DNS provider.
    4. (Optional) Pass any custom values in the Additional Options section.

    Adding a Global DNS Entry

    1. From the Global View, select Tools > Global DNS Entries.
    2. Click on Add DNS Entry.
    3. Fill out the form. For help, refer to Global DNS Entry Configuration.
    4. Click Create.

    Editing a Global DNS Provider

    The global administrators, creator of the Global DNS provider and any users added as members to a Global DNS provider, have owner access to that provider. Any members can edit the following fields:

    • Root Domain
    • Access Key & Secret Key
    • Members
    • Custom values

    1. From the Global View, select Tools > Global DNS Providers.

    2. For the Global DNS provider that you want to edit, click the ⋮ > Edit.

    Editing a Global DNS Entry

    The global administrators, creator of the Global DNS entry and any users added as members to a Global DNS entry, have owner access to that DNS entry. Any members can edit the following fields:

    • FQDN
    • Global DNS Provider
    • Target Projects or Multi-Cluster App
    • DNS TTL
    • Members

    Any users who can access the Global DNS entry can only add target projects that they have access to. However, users can remove any target project as there is no check to confirm if that user has access to the target project.

    Permission checks are relaxed for removing target projects in order to support situations where the user's permissions might have changed before they were able to delete the target project. Another use case could be that the target project was removed from the cluster before being removed from a target project of the Global DNS entry.

    1. From the Global View, select Tools > Global DNS Entries.

    2. For the Global DNS entry that you want to edit, click the ⋮ > Edit.

    Global DNS Entry Configuration

    FieldDescription
    FQDNEnter the FQDN you wish to program on the external DNS.
    ProviderSelect a Global DNS Provider from the list.
    Resolves ToSelect if this DNS entry will be for a multi-cluster application or for workloads in different projects.
    Multi-Cluster App TargetThe target for the global DNS entry. You will need to ensure that annotations are added to any ingresses for the applications that you want to target.
    DNS TTLConfigure the DNS time to live value in seconds. By default, it will be 300 seconds.
    Member AccessSearch for any users that you want to have the ability to manage this Global DNS entry.

    DNS Provider Configuration

    Route53​

    FieldExplanation
    NameEnter a Name for the provider.
    Root Domain(Optional) Enter the Root Domain of the hosted zone on AWS Route53. If this is not provided, Rancher's Global DNS Provider will work with all hosted zones that the AWS keys can access.
    Credential PathThe AWS credential path.
    Role ARNAn Amazon Resource Name.
    RegionAn AWS region.
    ZoneAn AWS zone.
    Access KeyEnter the AWS Access Key.
    Secret KeyEnter the AWS Secret Key.
    Member AccessUnder Member Access, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.

    CloudFlare​

    FieldExplanation
    NameEnter a Name for the provider.
    Root DomainOptional: Enter the Root Domain. In case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access.
    Proxy SettingWhen set to yes, the global DNS entry that gets created for the provider has proxy settings on.
    API EmailEnter the CloudFlare API Email.
    API KeyEnter the CloudFlare API Key.
    Member AccessSearch for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.

    AliDNS​

    Notes:

    • Alibaba Cloud SDK uses TZ data. It needs to be present on /usr/share/zoneinfo path of the nodes running local cluster, and it is mounted to the external DNS pods. If it is not available on the nodes, please follow the instruction to prepare it.
    • Different versions of AliDNS have different allowable TTL range, where the default TTL for a global DNS entry may not be valid. Please see the reference before adding an AliDNS entry.
    FieldExplanation
    NameEnter a Name for the provider.
    Root DomainOptional: Enter the Root Domain. In case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access.
    Access KeyEnter the Access Key.
    Secret KeyEnter the Secret Key.
    Member AccessSearch for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry.

    Adding Annotations to Ingresses to program the External DNS

    In order for Global DNS entries to be programmed, you will need to add a specific annotation on an ingress in your application or target project.

    For any application that you want targeted for your Global DNS entry, find an ingress associated with the application.

    This ingress needs to use a specific hostname and an annotation that should match the FQDN of the Global DNS entry.

    In order for the DNS to be programmed, the following requirements must be met:

    • The ingress routing rule must be set to use a hostname that matches the FQDN of the Global DNS entry.
    • The ingress must have an annotation (rancher.io/globalDNS.hostname) and the value of this annotation should match the FQDN of the Global DNS entry.

    Once the ingress in your multi-cluster application or in your target projects is in an active state, the FQDN will be programmed on the external DNS against the Ingress IP addresses.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.html index 2d9f2cf40e8..f5198d857c3 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/launching-apps.html @@ -5,13 +5,13 @@ Launching Catalog Apps | Rancher Manager - +
    Version: v2.0-v2.4

    Launching Catalog Apps

    Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the scope of the catalogs.

    If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    Prerequisites

    When Rancher deploys a catalog app, it launches an ephemeral instance of a Helm service account that has the permissions of the user deploying the catalog app. Therefore, a user cannot gain more access to the cluster through Helm or a catalog application than they otherwise would have.

    To launch an app from a catalog in Rancher, you must have at least one of the following permissions:

    • A project-member role in the target cluster, which gives you the ability to create, read, update, and delete the workloads
    • A cluster owner role for the cluster that include the target project

    Before launching an app, you'll need to either enable a built-in global catalog or add your own custom catalog.

    Launching a Catalog App

    1. From the Global view, open the project that you want to deploy an app to.

    2. From the main navigation bar, choose Apps. In versions before v2.2.0, choose Catalog Apps on the main navigation bar. Click Launch.

    3. Find the app that you want to launch, and then click View Now.

    4. Under Configuration Options enter a Name. By default, this name is also used to create a Kubernetes namespace for the application.

      • If you would like to change the Namespace, click Customize and enter a new name.
      • If you want to use a different namespace that already exists, click Customize, and then click Use an existing namespace. Choose a namespace from the list.

    5. Select a Template Version.

    6. Complete the rest of the Configuration Options.

      • For native Helm charts (i.e., charts from the Helm Stable or Helm Incubator catalogs), answers are provided as key value pairs in the Answers section.
      • Keys and values are available within Detailed Descriptions.
      • When entering answers, you must format them using the syntax rules found in Using Helm: The format and limitations of --set, as Rancher passes them as --set flags to Helm. For example, when entering an answer that includes two values separated by a comma (i.e., abc, bcd), wrap the values with double quotes (i.e., "abc, bcd").

    7. Review the files in Preview. When you're satisfied, click Launch.

    Result: Your application is deployed to your chosen namespace. You can view the application status from the project's Workloads view or Apps view. In versions before v2.2.0, this is the Catalog Apps view.

    Configuration Options

    For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in Using Helm: The format and limitations of –set, as Rancher passes them as --set flags to Helm.

    For example, when entering an answer that includes two values separated by a comma (i.e. abc, bcd), it is required to wrap the values with double quotes (i.e., "abc, bcd").

    Using a questions.yml file​

    If the Helm chart that you are deploying contains a questions.yml file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.

    Key Value Pairs for Native Helm Charts​

    For native Helm charts (i.e., charts from the Helm Stable or Helm Incubator catalogs or a custom Helm chart repository), answers are provided as key value pairs in the Answers section. These answers are used to override the default values.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/managing-apps.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/managing-apps.html index 89c95ea6701..e4d66ea495c 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/managing-apps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/managing-apps.html @@ -5,13 +5,13 @@ Managing Catalog Apps | Rancher Manager - +
    Version: v2.0-v2.4

    Managing Catalog Apps

    After deploying an application, one of the benefits of using an application versus individual workloads/resources is the ease of being able to manage many workloads/resources applications. Apps can be cloned, upgraded or rolled back.

    Cloning Catalog Applications​

    After an application is deployed, you can easily clone it to use create another application with almost the same configuration. It saves you the work of manually filling in duplicate information.

    Upgrading Catalog Applications​

    After an application is deployed, you can easily upgrade to a different template version.

    1. From the Global view, navigate to the project that contains the catalog application that you want to upgrade.

    2. From the main navigation bar, choose Apps. In versions before v2.2.0, choose Catalog Apps on the main navigation bar. Click Launch.

    3. Find the application that you want to upgrade, and then click the ⋮ to find Upgrade.

    4. Select the Template Version that you want to deploy.

    5. (Optional) Update your Configuration Options.

    6. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for Delete and recreate resources if needed during the upgrade.

      In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the upgrade.

    7. Review the files in the Preview section. When you're satisfied, click Launch.

    Result: Your application is updated. You can view the application status from the project's:

    • Workloads view
    • Apps view. In versions before v2.2.0, this is the Catalog Apps view.

    Rolling Back Catalog Applications​

    After an application has been upgraded, you can easily rollback to a different template version.

    1. From the Global view, navigate to the project that contains the catalog application that you want to upgrade.

    2. From the main navigation bar, choose Apps. In versions before v2.2.0, choose Catalog Apps on the main navigation bar. Click Launch.

    3. Find the application that you want to rollback, and then click the ⋮ to find Rollback.

    4. Select the Revision that you want to roll back to. By default, Rancher saves up to the last 10 revisions.

    5. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for Delete and recreate resources if needed during the upgrade.

      In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the rollback.

    6. Click Rollback.

    Result: Your application is updated. You can view the application status from the project's:

    • Workloads view
    • Apps view. In versions before v2.2.0, this is the Catalog Apps view.

    Deleting Catalog Application Deployments​

    As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to.

    Therefore, if you want to delete both an app and the namespace that contains the app, you should remove the app and the namespace separately:

    1. Uninstall the app using the app's uninstall function.

    2. From the Global view, navigate to the project that contains the catalog application that you want to delete.

    3. From the main menu, choose Namespaces.

    4. Find the namespace running your catalog app. Select it and click Delete.

    Result: The catalog application deployment and its namespace are deleted.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/multi-cluster-apps.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/multi-cluster-apps.html index 0192278290d..22009b622e2 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/multi-cluster-apps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/multi-cluster-apps.html @@ -5,13 +5,13 @@ Multi-Cluster Apps | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/tutorial.html b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/tutorial.html index 5aa03bb00fe..bf9ae9c65c8 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/tutorial.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/tutorial.html @@ -5,13 +5,13 @@ Tutorial: Example Custom Chart Creation | Rancher Manager - +
    Version: v2.0-v2.4

    Tutorial: Example Custom Chart Creation

    In this tutorial, you'll learn how to create a Helm chart and deploy it to a repository. The repository can then be used as a source for a custom catalog in Rancher.

    You can fill your custom catalogs with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience.

    For a complete walkthrough of developing charts, see the upstream Helm chart developer reference.

    1. Within the GitHub repo that you're using as your custom catalog, create a directory structure that mirrors the structure listed in the Chart Directory Structure.

      Rancher requires this directory structure, although app-readme.md and questions.yml are optional.

      Tip:

    2. Recommended: Create an app-readme.md file.

      Use this file to create custom text for your chart's header in the Rancher UI. You can use this text to notify users that the chart is customized for your environment or provide special instruction on how to use it.



      **Example**:
      $ cat ./app-readme.md

      # Wordpress ROCKS!

    3. Recommended: Create a questions.yml file.

      This file creates a form for users to specify deployment parameters when they deploy the custom chart. Without this file, users must specify the parameters manually using key value pairs, which isn't user-friendly.



      The example below creates a form that prompts users for persistent volume size and a storage class.

      For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](/v2.0-v2.4/how-to-guides/new-user-guides/helm-charts-in-rancher/creating-apps#question-variable-reference).
          categories:
          - Blog
          - CMS
          questions:
          - variable: persistence.enabled
            default: "false"
            description: "Enable persistent volume for WordPress"
            type: boolean
            required: true
            label: WordPress Persistent Volume Enabled
            show_subquestion_if: true
            group: "WordPress Settings"
            subquestions:
            - variable: persistence.size
              default: "10Gi"
              description: "WordPress Persistent Volume Size"
              type: string
              label: WordPress Volume Size
            - variable: persistence.storageClass
              default: ""
              description: "If undefined or null, uses the default StorageClass. Default to null"
              type: storageclass
              label: Default StorageClass for WordPress

    4. Check the customized chart into your GitHub repo.

    Result: Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html index ea5fd2bfe6c..65e97bb722a 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html @@ -5,13 +5,13 @@ Setting up Amazon ELB Network Load Balancer | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up Amazon ELB Network Load Balancer

    This how-to guide describes how to set up a Network Load Balancer (NLB) in Amazon's EC2 service that will direct traffic to multiple instances on EC2.

    These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required.

    This tutorial is about one possible way to set up your load balancer, not the only way. Other types of load balancers, such as a Classic Load Balancer or Application Load Balancer, could also direct traffic to the Rancher server nodes.

    Rancher only supports using the Amazon NLB when terminating traffic in tcp mode for port 443 rather than tls mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB.

    Setting up the Load Balancer

    Configuring an Amazon NLB is a multistage process:

    1. Create Target Groups
    2. Register Targets
    3. Create Your NLB
    4. Add listener to NLB for TCP port 80

    Requirements

    These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes.

    1. Create Target Groups

    Begin by creating two target groups for the TCP protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups.

    Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but it's convenient to add a listener for port 80, because traffic to port 80 will be automatically redirected to port 443.

    Regardless of whether an NGINX Ingress or Traefik Ingress controller is used, the Ingress should redirect traffic from port 80 to port 443.

    1. Log into the Amazon AWS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. Select Services and choose EC2, find the section Load Balancing and open Target Groups.
    3. Click Create target group to create the first target group, regarding TCP port 443.

    Note: Health checks are handled differently based on the Ingress. For details, refer to this section.

    Target Group (TCP port 443)​

    Configure the first target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-443
    Target typeinstance
    ProtocolTCP
    Port443
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Portoverride,80
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    Click Create target group to create the second target group, regarding TCP port 80.

    Target Group (TCP port 80)​

    Configure the second target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-80
    Target typeinstance
    ProtocolTCP
    Port80
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Porttraffic port
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    2. Register Targets

    Next, add your Linux nodes to both target groups.

    Select the target group named rancher-tcp-443, click the tab Targets and choose Edit.

    Select the instances (Linux nodes) you want to add, and click Add to registered.

    Screenshot Add targets to target group TCP port 443

    Screenshot Added targets to target group TCP port 443

    When the instances are added, click Save on the bottom right of the screen.

    Repeat those steps, replacing rancher-tcp-443 with rancher-tcp-80. The same instances need to be added as targets to this target group.

    3. Create Your NLB

    Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in 1. Create Target Groups.

    1. From your web browser, navigate to the Amazon EC2 Console.

    2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

    3. Click Create Load Balancer.

    4. Choose Network Load Balancer and click Create. Then complete each form.

    Step 1: Configure Load Balancer​

    Set the following fields in the form:

    • Name: rancher
    • Scheme: internal or internet-facing. The scheme that you choose for your NLB is dependent on the configuration of your instances and VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to internal rather than internet-facing.
    • Listeners: The Load Balancer Protocol should be TCP and the corresponding Load Balancer Port should be set to 443.
    • Availability Zones: Select Your VPC and Availability Zones.

    Step 2: Configure Routing​

    1. From the Target Group drop-down, choose Existing target group.
    2. From the Name drop-down, choose rancher-tcp-443.
    3. Open Advanced health check settings, and configure Interval to 10 seconds.

    Step 3: Register Targets​

    Since you registered your targets earlier, all you have to do is click Next: Review.

    Step 4: Review​

    Look over the load balancer details and click Create when you're satisfied.

    After AWS creates the NLB, click Close.

    4. Add listener to NLB for TCP port 80

    1. Select your newly created NLB and select the Listeners tab.

    2. Click Add listener.

    3. Use TCP:80 as Protocol : Port

    4. Click Add action and choose Forward to...

    5. From the Forward to drop-down, choose rancher-tcp-80.

    6. Click Save in the top right of the screen.

    Health Check Paths for NGINX Ingress and Traefik Ingresses

    K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default.

    For RKE Kubernetes clusters, NGINX Ingress is used by default, whereas for K3s Kubernetes clusters, Traefik is the default Ingress.

    • Traefik: The health check path is /ping. By default /ping is always matched (regardless of Host), and a response from Traefik itself is always served.
    • NGINX Ingress: The default backend of the NGINX Ingress controller has a /healthz endpoint. By default /healthz is always matched (regardless of Host), and a response from ingress-nginx itself is always served.

    To simulate an accurate health check, it is a best practice to use the Host header (Rancher hostname) combined with /ping or /healthz (for K3s or for RKE clusters, respectively) wherever possible, to get a response from the Rancher Pods, not the Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html index bc4d3e5c6c5..4cad16a61ea 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html @@ -5,14 +5,14 @@ Set up Infrastructure for a High Availability K3s Kubernetes Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Set up Infrastructure for a High Availability K3s Kubernetes Cluster

    This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.

    The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.

    For more information about each installation option, refer to this page.

    Note: These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure:

    • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • An external database to store the cluster data. We recommend MySQL.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up External Datastore​

    The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

    For a high-availability K3s installation, you will need to set a MySQL external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore.

    When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database.

    For an example of one way to set up the MySQL database, refer to this tutorial for setting up MySQL on Amazon's RDS service.

    For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

    3. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html index e38d2b75946..6ab2ccfe03d 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html @@ -5,14 +5,14 @@ Set up Infrastructure for a High Availability RKE Kubernetes Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Set up Infrastructure for a High Availability RKE Kubernetes Cluster

    This tutorial is intended to help you create a high-availability RKE cluster that can be used to install a Rancher server.

    Note: These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, Azure, or vSphere.
      • Note: When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. Please refer here for more information on Azure load balancer limitations.
    • A load balancer to direct front-end traffic to the three nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    These nodes must be in the same region/data center. You may place these servers in separate availability zones.

    Why three nodes?​

    In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

    The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on any of the three nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    3. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html index 19848ff249b..c4436cdf538 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html @@ -5,13 +5,13 @@ Setting up a MySQL Database in Amazon RDS | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up a MySQL Database in Amazon RDS

    This tutorial describes how to set up a MySQL database in Amazon's RDS.

    This database can later be used as an external datastore for a high-availability K3s Kubernetes cluster.

    1. Log into the Amazon AWS RDS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. In the left panel, click Databases.
    3. Click Create database.
    4. In the Engine type section, click MySQL.
    5. In the Version section, choose MySQL 5.7.22.
    6. In Settings section, under Credentials Settings, enter a master password for the admin master username. Confirm the password.
    7. Expand the Additional configuration section. In the Initial database name field, enter a name. The name can have only letters, numbers, and underscores. This name will be used to connect to the database.
    8. Click Create database.

    You'll need to capture the following information about the new database so that the K3s Kubernetes cluster can connect to it.

    To see this information in the Amazon RDS console, click Databases, and click the name of the database that you created.

    • Username: Use the admin username.
    • Password: Use the admin password.
    • Hostname: Use the Endpoint as the hostname. The endpoint is available in the Connectivity & security section.
    • Port: The port should be 3306 by default. You can confirm it in the Connectivity & security section.
    • Database name: Confirm the name by going to the Configuration tab. The name is listed under DB name.

    This information will be used to connect to the database in the following format:

    mysql://username:password@tcp(hostname:3306)/database-name

    For more information on configuring the datastore for K3s, refer to the K3s documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html index 17b082e4e4c..15fc63eead8 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html @@ -5,7 +5,7 @@ Setting up an NGINX Load Balancer | Rancher Manager - + @@ -23,7 +23,7 @@ server { listen 80; proxy_pass rancher_servers_http; }

    upstream rancher_servers_https {
        least_conn;
        server <IP_NODE_1>:443 max_fails=3 fail_timeout=5s;
        server <IP_NODE_2>:443 max_fails=3 fail_timeout=5s;
        server <IP_NODE_3>:443 max_fails=3 fail_timeout=5s;
    }
    server {
        listen     443;
        proxy_pass rancher_servers_https;
    }

    }


    1. Save nginx.conf to your load balancer at the following path: /etc/nginx/nginx.conf.

    2. Load the updates to your NGINX configuration by running the following command:

      # nginx -s reload

    Option - Run NGINX as Docker container​

    Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited Example NGINX config as /etc/nginx.conf and run the following command to launch the NGINX container:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /etc/nginx.conf:/etc/nginx/nginx.conf \
      nginx:1.14
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html index 59f7ba9e0dc..3045f53b882 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html @@ -5,13 +5,13 @@ Setting up Nodes in Amazon EC2 | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up Nodes in Amazon EC2

    In this tutorial, you will learn one way to set up Linux nodes for the Rancher management server. These nodes will fulfill the node requirements for OS, Docker, hardware, and networking.

    If the Rancher server will be installed on an RKE Kubernetes cluster, you should provision three instances.

    If the Rancher server will be installed on a K3s Kubernetes cluster, you only need to provision two instances.

    If the Rancher server is installed in a single Docker container, you only need one instance.

    1. Optional Preparation​

    • Create IAM role: To allow Rancher to manipulate AWS resources, such as provisioning new storage or new nodes, you will need to configure Amazon as a cloud provider. There are several things you'll need to do to set up the cloud provider on EC2, but part of this process is setting up an IAM role for the Rancher server nodes. For the full details on setting up the cloud provider, refer to this page.
    • Create security group: We also recommend setting up a security group for the Rancher nodes that complies with the port requirements for Rancher nodes.

    2. Provision Instances​

    1. Log into the Amazon AWS EC2 Console to get started. Make sure to take note of the Region where your EC2 instances (Linux nodes) are created, because all of the infrastructure for the Rancher management server should be in the same region.
    2. In the left panel, click Instances.
    3. Click Launch Instance.
    4. In the section called Step 1: Choose an Amazon Machine Image (AMI), we will use Ubuntu 18.04 as the Linux OS, using ami-0d1cd67c26f5fca19 (64-bit x86). Go to the Ubuntu AMI and click Select.
    5. In the Step 2: Choose an Instance Type section, select the t2.medium type.
    6. Click Next: Configure Instance Details.
    7. In the Number of instances field, enter the number of instances. A high-availability K3s cluster requires only two instances, while a high-availability RKE cluster requires three instances.
    8. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the IAM role field.
    9. Click Next: Add Storage, Next: Add Tags, and Next: Configure Security Group.
    10. In Step 6: Configure Security Group, select a security group that complies with the port requirements for Rancher nodes.
    11. Click Review and Launch.
    12. Click Launch.
    13. Choose a new or existing key pair that you will use to connect to your instance later. If you are using an existing key pair, make sure you already have access to the private key.
    14. Click Launch Instances.

    Result: You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking. Next, you will install Docker on each node.

    3. Install Docker and Create User​

    1. From the AWS EC2 console, click Instances in the left panel.
    2. Go to the instance that you want to install Docker on. Select the instance and click Actions > Connect.
    3. Connect to the instance by following the instructions on the screen that appears. Copy the Public DNS of the instance. An example command to SSH into the instance is as follows:
    sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance]
    1. Run the following command on the instance to install Docker with one of Rancher's installation scripts:
    curl https://releases.rancher.com/install-docker/18.09.sh | sh
    1. When you are connected to the instance, run the following command on the instance to create a user:
    sudo usermod -aG docker ubuntu
    1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server.

    To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher’s Docker installation scripts.

    Result: You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking.

    Next Steps for RKE Kubernetes Cluster Nodes​

    If you are going to install an RKE cluster on the new nodes, take note of the IPv4 Public IP and Private IP of each node. This information can be found on the Description tab for each node after it is created. The public and private IP will be used to populate the address and internal_address of each node in the RKE cluster configuration file, rancher-cluster.yml.

    RKE will also need access to the private key to connect to each node. Therefore, you might want to take note of the path to your private keys to connect to the nodes, which can also be included in the rancher-cluster.yml under the ssh_key_path directive for each node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html index fe54693f653..15be49e9550 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html @@ -5,13 +5,13 @@ About High-availability Installations | Rancher Manager - +
    Version: v2.0-v2.4

    About High-availability Installations

    We recommend using Helm, a Kubernetes package manager, to install Rancher on a dedicated Kubernetes cluster. This is called a high-availability Kubernetes installation because increased availability is achieved by running Rancher on multiple nodes.

    In a standard installation, Kubernetes is first installed on three nodes that are hosted in an infrastructure provider such as Amazon's EC2 or Google Compute Engine.

    Then Helm is used to install Rancher on top of the Kubernetes cluster. Helm uses Rancher's Helm chart to install a replica of Rancher on each of the three nodes in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster, in order to increase Rancher's availability.

    The Rancher server data is stored on etcd. This etcd database also runs on all three nodes, and requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup.

    For information on how Rancher works, regardless of the installation method, refer to the architecture section.

    • DNS for Rancher should resolve to a layer 4 load balancer
    • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
    • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
    • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
    Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers

    High-availability Kubernetes Installation of Rancher

    Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html index 4222d903215..884ac3d50ab 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html @@ -5,14 +5,14 @@ Setting up a High-availability K3s Kubernetes Cluster for Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up a High-availability K3s Kubernetes Cluster for Rancher

    This section describes how to install a Kubernetes cluster according to the best practices for the Rancher server environment.

    For systems without direct internet access, refer to the air gap installation instructions.

    Single-node Installation Tip: In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Prerequisites

    These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in this section.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

    Installing Kubernetes

    1. Install Kubernetes and Set up the K3s Server​

    When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier.

    1. Connect to one of the Linux nodes that you have prepared to run the Rancher server.

    2. On the Linux node, run this command to start the K3s server and connect it to the external datastore:

      curl -sfL https://get.k3s.io | sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"

      To specify the K3s version, use the INSTALL_K3S_VERSION environment variable:

      curl -sfL https://get.k3s.io |  INSTALL_K3S_VERSION=vX.Y.Z sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"

      Note: The datastore endpoint can also be passed in using the environment variable $K3S_DATASTORE_ENDPOINT.

    3. Repeat the same command on your second K3s server node.

    2. Confirm that K3s is Running​

    To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes:

    sudo k3s kubectl get nodes

    Then you should see two nodes with the master role:

    ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes
    NAME               STATUS   ROLES    AGE    VERSION
    ip-172-31-60-194   Ready    master   44m    v1.17.2+k3s1
    ip-172-31-63-88    Ready    master   6m8s   v1.17.2+k3s1

    Then test the health of the cluster pods:

    sudo k3s kubectl get pods --all-namespaces

    Result: You have successfully set up a K3s Kubernetes cluster.

    3. Save and Start Using the kubeconfig File​

    When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    4. Check the Health of Your Cluster Pods​

    Now that you have set up the kubeconfig file, you can use kubectl to access the cluster from your local machine.

    Check that all the required pods and containers are healthy are ready to continue:

    ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces
    NAMESPACE       NAME                                      READY   STATUS    RESTARTS   AGE
    kube-system     metrics-server-6d684c7b5-bw59k            1/1     Running   0          8d
    kube-system     local-path-provisioner-58fb86bdfd-fmkvd   1/1     Running   0          8d
    kube-system     coredns-d798c9dd-ljjnf                    1/1     Running   0          8d

    Result: You have confirmed that you can access the cluster with kubectl and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html index 54b4ce67533..135c6a1675a 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html @@ -5,7 +5,7 @@ Setting up a High-availability RKE Kubernetes Cluster | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.0-v2.4

    Setting up a High-availability RKE Kubernetes Cluster

    This section describes how to install a Kubernetes cluster. This cluster should be dedicated to run only the Rancher server.

    For Rancher before v2.4, Rancher should be installed on an RKE Kubernetes cluster. RKE is a CNCF-certified Kubernetes distribution that runs entirely within Docker containers.

    As of Rancher v2.4, the Rancher management server can be installed on either an RKE cluster or a K3s Kubernetes cluster. K3s is also a fully certified Kubernetes distribution released by Rancher, but is newer than RKE. We recommend installing Rancher on K3s because K3s is easier to use, and more lightweight, with a binary size of less than 100 MB. Note: After Rancher is installed on an RKE cluster, there is no migration path to a K3s setup at this time.

    The Rancher management server can only be run on Kubernetes cluster in an infrastructure provider where Kubernetes is installed using RKE or K3s. Use of Rancher on hosted Kubernetes providers, such as EKS, is not supported.

    For systems without direct internet access, refer to Air Gap: Kubernetes install.

    Single-node Installation Tip: In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node RKE cluster, configure only one node in the cluster.yml . The single node should have all three roles: etcd, controlplane, and worker.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Installing Kubernetes

    Required CLI Tools​

    Install kubectl, a Kubernetes command-line tool.

    Also install RKE, the Rancher Kubernetes Engine, a Kubernetes distribution and command-line tool.

    1. Create the cluster configuration file​

    In this section, you will create a Kubernetes cluster configuration file called rancher-cluster.yml. In a later step, when you set up the cluster with an RKE command, it will use this file to install Kubernetes on your nodes.

    Using the sample below as a guide, create the rancher-cluster.yml file. Replace the IP addresses in the nodes list with the IP address or DNS names of the 3 nodes you created.

    If your node has public and internal addresses, it is recommended to set the internal_address: so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the internal_address: if you want to use self-referencing security groups or firewalls.

    RKE will need to connect to each node over SSH, and it will look for a private key in the default location of ~/.ssh/id_rsa. If your private key for a certain node is in a different location than the default, you will also need to configure the ssh_key_path option for that node.

    nodes:
      - address: 165.227.114.63
        internal_address: 172.16.22.12
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.116.167
        internal_address: 172.16.32.37
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.127.226
        internal_address: 172.16.42.73
        user: ubuntu
        role: [controlplane, worker, etcd]

    services:
      etcd:
        snapshot: true
        creation: 6h
        retention: 24h

    # Required for external TLS termination with
    # ingress-nginx v0.22+
    ingress:
      provider: nginx
      options:
        use-forwarded-headers: "true"
    Common RKE Nodes Options
    OptionRequiredDescription
    addressyesThe public DNS or IP address
    useryesA user that can run docker commands
    roleyesList of Kubernetes roles assigned to the node
    internal_addressnoThe private DNS or IP address for internal cluster traffic
    ssh_key_pathnoPath to SSH private key used to authenticate to the node (defaults to ~/.ssh/id_rsa)

    Advanced Configurations: RKE has many configuration options for customizing the install to suit your specific environment.

    Please see the RKE Documentation for the full list of options and capabilities.

    For tuning your etcd cluster for larger Rancher installations, see the etcd settings guide.

    2. Run RKE​

    rke up --config ./rancher-cluster.yml

    When finished, it should end with the line: Finished building Kubernetes cluster successfully.

    3. Test Your Cluster​

    This section describes how to set up your workspace so that you can interact with this cluster using the kubectl command-line tool.

    Assuming you have installed kubectl, you need to place the kubeconfig file in a location where kubectl can reach it. The kubeconfig file contains the credentials necessary to access your cluster with kubectl.

    When you ran rke up, RKE should have created a kubeconfig file named kube_config_rancher-cluster.yml. This file has the credentials for kubectl and helm.

    Note: If you have used a different file name from rancher-cluster.yml, then the kube config file will be named kube_config_<FILE_NAME>.yml.

    Move this file to $HOME/.kube/config, or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_rancher-cluster.yml:

    export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml

    Test your connectivity with kubectl and see if all your nodes are in Ready state:

    kubectl get nodes

    NAME                          STATUS    ROLES                      AGE       VERSION
    165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.13.5

    4. Check the Health of Your Cluster Pods​

    Check that all the required pods and containers are healthy are ready to continue.

    • Pods are in Running or Completed state.
    • READY column shows all the containers are running (i.e. 3/3) for pods with STATUS Running
    • Pods with STATUS Completed are run-once Jobs. For these pods READY should be 0/1.
    kubectl get pods --all-namespaces

    NAMESPACE       NAME                                      READY     STATUS      RESTARTS   AGE
    ingress-nginx   nginx-ingress-controller-tnsn4            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-tw2ht            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-v874b            1/1       Running     0          30s
    kube-system     canal-jp4hz                               3/3       Running     0          30s
    kube-system     canal-z2hg8                               3/3       Running     0          30s
    kube-system     canal-z6kpw                               3/3       Running     0          30s
    kube-system     kube-dns-7588d5b5f5-sf4vh                 3/3       Running     0          30s
    kube-system     kube-dns-autoscaler-5db9bbb766-jz2k6      1/1       Running     0          30s
    kube-system     metrics-server-97bc649d5-4rl2q            1/1       Running     0          30s
    kube-system     rke-ingress-controller-deploy-job-bhzgm   0/1       Completed   0          30s
    kube-system     rke-kubedns-addon-deploy-job-gl7t4        0/1       Completed   0          30s
    kube-system     rke-metrics-addon-deploy-job-7ljkc        0/1       Completed   0          30s
    kube-system     rke-network-plugin-deploy-job-6pbgj       0/1       Completed   0          30s

    This confirms that you have successfully installed a Kubernetes cluster that the Rancher server will run on.

    5. Save Your Files​

    Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

    Save a copy of the following files in a secure location:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
    • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains credentials for full access to the cluster.

      The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html index 1c3a26587e2..b60319fd0e8 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html @@ -5,13 +5,13 @@ Recommended Cluster Architecture | Rancher Manager - +
    Version: v2.0-v2.4

    Recommended Cluster Architecture

    There are three roles that can be assigned to nodes: etcd, controlplane and worker.

    Separating Worker Nodes from Nodes with Other Roles​

    When designing your cluster(s), you have two options:

    • Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the port requirements.
    • Assign the etcd and controlplane roles to the same nodes. These nodes must meet the hardware requirements for both roles.

    In either case, the worker role should not be used or added to nodes with the etcd or controlplane role.

    Therefore, each node should have one of the following role configurations:

    • etcd
    • controlplane
    • Both etcd and controlplane
    • worker

    The cluster should have:

    • At least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • At least two nodes with the role controlplane for master component high availability.
    • At least two nodes with the role worker for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    Number of Controlplane Nodes​

    Adding more than one node with the controlplane role makes every master component highly available.

    Number of etcd Nodes​

    The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the etcd role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an etcd node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.

    Nodes with etcd roleMajorityFailure Tolerance
    110
    220
    321
    431
    532
    642
    743
    853
    954

    References:

    Number of Worker Nodes​

    Adding more than one node with the worker role will make sure your workloads can be rescheduled if a node fails.

    Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications​

    You may have noticed that our Kubernetes Install instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the worker role. However, for your Rancher installation, this three node cluster is valid, because:

    • It allows one etcd node failure.
    • It maintains multiple instances of the master components by having multiple controlplane nodes.
    • No other workloads than Rancher itself should be created on this cluster.

    References​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html index e7c66ba96e4..be43031e6d4 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html @@ -5,13 +5,13 @@ Roles for Nodes in Kubernetes | Rancher Manager - +
    Version: v2.0-v2.4

    Roles for Nodes in Kubernetes

    This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster.

    This diagram is applicable to Kubernetes clusters launched with Rancher using RKE..

    Cluster diagram

    Lines show the traffic flow between components. Colors are used purely for visual aid

    etcd

    Nodes with the etcd role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.

    Note: Nodes with the etcd role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    controlplane

    Nodes with the controlplane role run the Kubernetes master components (excluding etcd, as it's a separate role). See Kubernetes: Master Components for a detailed list of components.

    Note: Nodes with the controlplane role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    kube-apiserver​

    The Kubernetes API server (kube-apiserver) scales horizontally. Each node with the role controlplane will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.

    kube-controller-manager​

    The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the kube-controller-manager will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    kube-scheduler​

    The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the kube-scheduler will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    worker

    Nodes with the worker role run the Kubernetes node components. See Kubernetes: Node Components for a detailed list of components.

    References

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.html index 76ffa64a27e..a7c6fcab1a7 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/import-existing-clusters.html @@ -5,14 +5,14 @@ Importing Existing Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Importing Existing Clusters

    Available as of v2.0.x-v2.4.x

    When managing an imported cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

    Rancher features, including management of cluster, role-based access control, policy, and workloads, are available for imported clusters. Note that Rancher does not automate the provisioning or scaling of imported clusters.

    For all imported Kubernetes clusters except for K3s clusters, the configuration of an imported cluster still has to be edited outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters.

    Rancher v2.4 added the capability to import a K3s cluster into Rancher, as well as the ability to upgrade Kubernetes by editing the cluster in the Rancher UI.

    Features

    After importing a cluster, the cluster owner can:

    After importing a K3s cluster, the cluster owner can also upgrade Kubernetes from the Rancher UI.

    Prerequisites

    If your existing Kubernetes cluster already has a cluster-admin role defined, you must have this cluster-admin privilege to import the cluster into Rancher.

    In order to apply the privilege, you need to run:

    kubectl create clusterrolebinding cluster-admin-binding \
      --clusterrole cluster-admin \
      --user [USER_ACCOUNT]

    before running the kubectl command to import the cluster.

    By default, GKE users are not given this privilege, so you will need to run the command before importing GKE clusters. To learn more about role-based access control for GKE, please click here.

    If you are importing a K3s cluster, make sure the cluster.yml is readable. It is protected by default. For details, refer to Configuring a K3s cluster to enable importation to Rancher.

    Importing a Cluster

    1. From the Clusters page, click Add Cluster.
    2. Choose Import.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.}
    5. Click Create.
    6. The prerequisite for cluster-admin privileges is shown (see Prerequisites above), including an example command to fulfil the prerequisite.
    7. Copy the kubectl command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run kubectl get nodes to verify before running the command shown in Rancher.
    8. If you are using self signed certificates, you will receive the message certificate signed by unknown authority. To work around this validation, copy the command starting with curl displayed in Rancher to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import.
    9. When you finish running the command(s) on your node, click Done.

    Result:

    • Your cluster is imported and assigned a state of Pending. Rancher is deploying resources to manage your cluster.
    • You can access your cluster after its state is updated to Active.
    • Active clusters are assigned two Projects: Default (containing the namespace default) and System (containing the namespaces cattle-system, ingress-nginx, kube-public and kube-system, if present).

    Note: You can not re-import a cluster that is currently active in a Rancher setup.

    Imported K3s Clusters

    You can now import a K3s Kubernetes cluster into Rancher. K3s is a lightweight, fully compliant Kubernetes distribution. You can also upgrade Kubernetes by editing the K3s cluster in the Rancher UI.

    Additional Features for Imported K3s Clusters​

    Available as of v2.4.0

    When a K3s cluster is imported, Rancher will recognize it as K3s, and the Rancher UI will expose the following features in addition to the functionality for other imported clusters:

    • The ability to upgrade the K3s version
    • The ability to configure the maximum number of nodes that will be upgraded concurrently
    • The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster.

    Configuring K3s Cluster Upgrades​

    It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider.

    The concurrency is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the concurrency, the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed.

    • Controlplane concurrency: The maximum number of server nodes to upgrade at a single time; also the maximum unavailable server nodes
    • Worker concurrency: The maximum number worker nodes to upgrade at the same time; also the maximum unavailable worker nodes

    In the K3s documentation, controlplane nodes are called server nodes. These nodes run the Kubernetes master, which maintains the desired state of the cluster. In K3s, these controlplane nodes have the capability to have workloads scheduled to them by default.

    Also in the K3s documentation, nodes with the worker role are called agent nodes. Any workloads or pods that are deployed in the cluster can be scheduled to these nodes by default.

    Configuring a K3s Cluster to Enable Importation to Rancher​

    The K3s server needs to be configured to allow writing to the kubeconfig file.

    This can be accomplished by passing --write-kubeconfig-mode 644 as a flag during installation:

    $ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

    The option can also be specified using the environment variable K3S_KUBECONFIG_MODE:

    $ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -

    Debug Logging and Troubleshooting for Imported K3s Clusters​

    Nodes are upgraded by the system upgrade controller running in the downstream cluster. Based on the cluster configuration, Rancher deploys two plans to upgrade K3s nodes: one for controlplane nodes and one for workers. The system upgrade controller follows the plans and upgrades the nodes.

    To enable debug logging on the system upgrade controller deployment, edit the configmap to set the debug environment variable to true. Then restart the system-upgrade-controller pod.

    Logs created by the system-upgrade-controller can be viewed by running this command:

    kubectl logs -n cattle-system system-upgrade-controller

    The current status of the plans can be viewed with this command:

    kubectl get plans -A -o yaml

    If the cluster becomes stuck in upgrading, restart the system-upgrade-controller.

    To prevent issues when upgrading, the Kubernetes upgrade best practices should be followed.

    Annotating Imported Clusters

    For all types of imported Kubernetes clusters except for K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured.

    Therefore, when Rancher imports a cluster, it assumes that several capabilities are disabled by default. Rancher assumes this in order to avoid exposing UI options to the user even when the capabilities are not enabled in the imported cluster.

    However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster.

    By annotating an imported cluster, it is possible to indicate to Rancher that a cluster was given a pod security policy, or another capability, outside of Rancher.

    This example annotation indicates that a pod security policy is enabled:

    "capabilities.cattle.io/pspEnabled": "true"

    The following annotation indicates Ingress capabilities. Note that that the values of non-primitive objects need to be JSON encoded, with quotations escaped.

    "capabilities.cattle.io/ingressCapabilities": "[
      {
        "customDefaultBackend":true,
        "ingressProvider":"asdf"
      }
    ]"

    These capabilities can be annotated for the cluster:

    • ingressCapabilities
    • loadBalancerCapabilities
    • nodePoolScalingSupported
    • nodePortRange
    • pspEnabled
    • taintSupport

    All the capabilities and their type definitions can be viewed in the Rancher API view, at [Rancher Server URL]/v3/schemas/capabilities.

    To annotate an imported cluster,

    1. Go to the cluster view in Rancher and select ⋮ > Edit.
    2. Expand the Labels & Annotations section.
    3. Click Add Annotation.
    4. Add an annotation to the cluster with the format capabilities/<capability>: <value> where value is the cluster capability that will be overridden by the annotation. In this scenario, Rancher is not aware of any capabilities of the cluster until you add the annotation.
    5. Click Save.

    Result: The annotation does not give the capabilities to the cluster, but it does indicate to Rancher that the cluster has those capabilities.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html index 7ea780780b7..e59efee8e70 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html @@ -5,13 +5,13 @@ Rancher Agents | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher Agents

    There are two different agent resources deployed on Rancher managed clusters:

    For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the architecture

    cattle-cluster-agent​

    The cattle-cluster-agent is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The cattle-cluster-agent is deployed using a Deployment resource.

    cattle-node-agent​

    The cattle-node-agent is used to interact with nodes in a Rancher Launched Kubernetes cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node. The cattle-node-agent is used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when cattle-cluster-agent is unavailable.

    Note: In Rancher v2.2.4 and lower, the cattle-node-agent pods did not tolerate all taints, causing Kubernetes upgrades to fail on these nodes. The fix for this has been included in Rancher v2.2.5 and higher.

    Scheduling rules​

    Applies to v2.3.0 up to v2.5.3

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists
    cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

    The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

    The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

    WeightExpression
    100node-role.kubernetes.io/controlplane:In:"true"
    1node-role.kubernetes.io/etcd:In:"true"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html index 76c2ea0483c..a796e9adc60 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html @@ -5,13 +5,13 @@ Setting up the Amazon Cloud Provider | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up the Amazon Cloud Provider

    When using the Amazon cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an AWS Elastic Load Balancer (ELB) when choosing Layer-4 Load Balancer in Port Mapping or when launching a Service with type: LoadBalancer.
    • Persistent Volumes: Allows you to use AWS Elastic Block Stores (EBS) for persistent volumes.

    See cloud-provider-aws README for all information regarding the Amazon cloud provider.

    To set up the Amazon cloud provider,

    1. Create an IAM role and attach to the instances
    2. Configure the ClusterID

    1. Create an IAM Role and attach to the instances​

    All nodes added to the cluster must be able to interact with EC2 so that they can create and remove resources. You can enable this interaction by using an IAM role attached to the instance. See Amazon documentation: Creating an IAM Role how to create an IAM role. There are two example policies:

    • The first policy is for the nodes with the controlplane role. These nodes have to be able to create/remove EC2 resources. The following IAM policy is an example, please remove any unneeded permissions for your use case.
    • The second policy is for the nodes with the etcd or worker role. These nodes only have to be able to retrieve information from EC2.

    While creating an Amazon EC2 cluster, you must fill in the IAM Instance Profile Name (not ARN) of the created IAM role when creating the Node Template.

    While creating a Custom cluster, you must manually attach the IAM role to the instance(s).

    IAM Policy for nodes with the controlplane role:

    {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "autoscaling:DescribeAutoScalingGroups",
          "autoscaling:DescribeLaunchConfigurations",
          "autoscaling:DescribeTags",
          "ec2:DescribeInstances",
          "ec2:DescribeRegions",
          "ec2:DescribeRouteTables",
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeSubnets",
          "ec2:DescribeVolumes",
          "ec2:CreateSecurityGroup",
          "ec2:CreateTags",
          "ec2:CreateVolume",
          "ec2:ModifyInstanceAttribute",
          "ec2:ModifyVolume",
          "ec2:AttachVolume",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:CreateRoute",
          "ec2:DeleteRoute",
          "ec2:DeleteSecurityGroup",
          "ec2:DeleteVolume",
          "ec2:DetachVolume",
          "ec2:RevokeSecurityGroupIngress",
          "ec2:DescribeVpcs",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:AttachLoadBalancerToSubnets",
          "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancerPolicy",
          "elasticloadbalancing:CreateLoadBalancerListeners",
          "elasticloadbalancing:ConfigureHealthCheck",
          "elasticloadbalancing:DeleteLoadBalancer",
          "elasticloadbalancing:DeleteLoadBalancerListeners",
          "elasticloadbalancing:DescribeLoadBalancers",
          "elasticloadbalancing:DescribeLoadBalancerAttributes",
          "elasticloadbalancing:DetachLoadBalancerFromSubnets",
          "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
          "elasticloadbalancing:ModifyLoadBalancerAttributes",
          "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
          "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:CreateListener",
          "elasticloadbalancing:CreateTargetGroup",
          "elasticloadbalancing:DeleteListener",
          "elasticloadbalancing:DeleteTargetGroup",
          "elasticloadbalancing:DescribeListeners",
          "elasticloadbalancing:DescribeLoadBalancerPolicies",
          "elasticloadbalancing:DescribeTargetGroups",
          "elasticloadbalancing:DescribeTargetHealth",
          "elasticloadbalancing:ModifyListener",
          "elasticloadbalancing:ModifyTargetGroup",
          "elasticloadbalancing:RegisterTargets",
          "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
          "iam:CreateServiceLinkedRole",
          "kms:DescribeKey"
        ],
        "Resource": [
          "*"
        ]
      }
    ]
    }

    IAM policy for nodes with the etcd or worker role:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "ec2:DescribeRegions",
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:GetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:BatchGetImage"
            ],
            "Resource": "*"
        }
    ]
    }

    2. Configure the ClusterID​

    The following resources need to tagged with a ClusterID:

    • Nodes: All hosts added in Rancher.
    • Subnet: The subnet used for your cluster.
    • Security Group: The security group used for your cluster.

    Note: Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB).

    When you create an Amazon EC2 Cluster, the ClusterID is automatically configured for the created nodes. Other resources still need to be tagged manually.

    Use the following tag:

    Key = kubernetes.io/cluster/CLUSTERID Value = owned

    CLUSTERID can be any string you like, as long as it is equal across all tags set.

    Setting the value of the tag to owned tells the cluster that all resources with this tag are owned and managed by this cluster. If you share resources between clusters, you can change the tag to:

    Key = kubernetes.io/cluster/CLUSTERID Value = shared.

    Using Amazon Elastic Container Registry (ECR)​

    The kubelet component has the ability to automatically obtain ECR credentials, when the IAM profile mentioned in Create an IAM Role and attach to the instances is attached to the instance(s). When using a Kubernetes version older than v1.15.0, the Amazon cloud provider needs be configured in the cluster. Starting with Kubernetes version v1.15.0, the kubelet can obtain ECR credentials without having the Amazon cloud provider configured in the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html index fc901c6bc22..652ae72cd7f 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html @@ -5,13 +5,13 @@ Setting up the Azure Cloud Provider | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up the Azure Cloud Provider

    When using the Azure cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an Azure Load Balancer within a specific Network Security Group.

    • Persistent Volumes: Supports using Azure Blob disks and Azure Managed Disks with standard and premium storage accounts.

    • Network Storage: Support Azure Files via CIFS mounts.

    The following account types are not supported for Azure Subscriptions:

    • Single tenant accounts (i.e. accounts with no subscriptions).
    • Multi-subscription accounts.

    To set up the Azure cloud provider following credentials need to be configured:

    1. Set up the Azure Tenant ID
    2. Set up the Azure Client ID and Azure Client Secret
    3. Configure App Registration Permissions
    4. Set up Azure Network Security Group Name

    1. Set up the Azure Tenant ID​

    Visit Azure portal, login and go to Azure Active Directory and select Properties. Your Directory ID is your Tenant ID (tenantID).

    If you want to use the Azure CLI, you can run the command az account show to get the information.

    2. Set up the Azure Client ID and Azure Client Secret​

    Visit Azure portal, login and follow the steps below to create an App Registration and the corresponding Azure Client ID (aadClientId) and Azure Client Secret (aadClientSecret).

    1. Select Azure Active Directory.
    2. Select App registrations.
    3. Select New application registration.
    4. Choose a Name, select Web app / API as Application Type and a Sign-on URL which can be anything in this case.
    5. Select Create.

    In the App registrations view, you should see your created App registration. The value shown in the column APPLICATION ID is what you need to use as Azure Client ID.

    The next step is to generate the Azure Client Secret:

    1. Open your created App registration.
    2. In the Settings view, open Keys.
    3. Enter a Key description, select an expiration time and select Save.
    4. The generated value shown in the column Value is what you need to use as Azure Client Secret. This value will only be shown once.

    3. Configure App Registration Permissions​

    The last thing you will need to do, is assign the appropriate permissions to your App registration.

    1. Go to More services, search for Subscriptions and open it.
    2. Open Access control (IAM).
    3. Select Add.
    4. For Role, select Contributor.
    5. For Select, select your created App registration name.
    6. Select Save.

    4. Set up Azure Network Security Group Name​

    A custom Azure Network Security Group (securityGroupName) is needed to allow Azure Load Balancers to work.

    If you provision hosts using Rancher Machine Azure driver, you will need to edit them manually to assign them to this Network Security Group.

    You should already assign custom hosts to this Network Security Group during provisioning.

    Only hosts expected to be load balancer back ends need to be in this group.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html index d361b6368c1..ae8d71ee7fc 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html @@ -5,13 +5,13 @@ Setting up the Google Compute Engine Cloud Provider | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up the Google Compute Engine Cloud Provider

    In this section, you'll learn how to enable the Google Compute Engine (GCE) cloud provider for custom clusters in Rancher. A custom cluster is one in which Rancher installs Kubernetes on existing nodes.

    The official Kubernetes documentation for the GCE cloud provider is here.

    Prerequisites: The service account of Identity and API access on GCE needs the Computer Admin permission.

    If you are using Calico,

    1. Go to the cluster view in the Rancher UI, and click ⋮ > Edit.

    2. Click Edit as YAML, and enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        network:
          options:
            calico_cloud_provider: "gce"
          plugin: "calico"

    If you are using Canal or Flannel,

    1. Go to the cluster view in the Rancher UI, and click ⋮ > Edit.

    2. Click Edit as YAML, and enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        services:
          kube_controller:
            extra_args:
              configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.html index 395967144ea..83a965837ed 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/vsphere.html @@ -5,13 +5,13 @@ Setting up the vSphere Cloud Provider | Rancher Manager - +
    Version: v2.0-v2.4

    Setting up the vSphere Cloud Provider

    In this section, you'll learn how to set up the vSphere cloud provider for a Rancher managed RKE Kubernetes cluster in vSphere.

    Follow these steps while creating the vSphere cluster in Rancher:

    1. Set Cloud Provider option to Custom.

    2. Click on Edit as YAML

    3. Insert the following structure to the pre-populated cluster YAML. As of Rancher v2.3+, this structure must be placed under rancher_kubernetes_engine_config. In versions before v2.3, it has to be defined as a top-level field. Note that the name must be set to vsphere.

      rancher_kubernetes_engine_config: # Required as of Rancher v2.3+
        cloud_provider:
            name: vsphere
            vsphereCloudProvider:
                [Insert provider configuration]

    Rancher uses RKE (the Rancher Kubernetes Engine) to provision Kubernetes clusters. Refer to the vSphere configuration reference in the RKE documentation for details about the properties of the vsphereCloudProvider directive.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html index c31849eb5c7..a0e35b84362 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html @@ -5,13 +5,13 @@ Creating a DigitalOcean Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating a DigitalOcean Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in DigitalOcean.

    First, you will set up your DigitalOcean cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in DigitalOcean.

    Then you will create a DigitalOcean cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select DigitalOcean.
    5. Enter your Digital Ocean credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for DigitalOcean will allow Rancher to provision new nodes in DigitalOcean. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for DigitalOcean. For help filling out the form, refer to DigitalOcean Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    1. From the Clusters page, click Add Cluster.
    2. Choose DigitalOcean.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. Add one or more node pools to your cluster. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.
    7. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html index 2b6e2523fdb..9d8a7a76235 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html @@ -5,13 +5,13 @@ Creating an Amazon EC2 Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating an Amazon EC2 Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in Amazon EC2.

    First, you will set up your EC2 cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in EC2.

    Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    Prerequisites​

    Note: Rancher v2.4.6 and v2.4.7 had an issue where the kms:ListKeys permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.

    Creating an EC2 Cluster

    The steps to create a cluster differ based on your Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials and information from EC2
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select Amazon.
    5. In the Region field, select the AWS region where your cluster nodes will be located.
    6. Enter your AWS EC2 Access Key and Secret Key.
    7. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials and information from EC2​

    Creating a node template for EC2 will allow Rancher to provision new nodes in EC2. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for EC2. For help filling out the form, refer to EC2 Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Add one or more node pools to your cluster. For more information about node pools, see this section.

    1. From the Clusters page, click Add Cluster.
    2. Choose Amazon EC2.
    3. Enter a Cluster Name.
    4. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.
    5. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. Refer to Selecting Cloud Providers to configure the Kubernetes Cloud Provider. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    ### Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    IAM Policies

    Note: Rancher v2.4.6 and v2.4.7 had an issue where the kms:ListKeys permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.

    Example IAM Policy​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy with PassRole​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "iam:PassRole",
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*",
                    "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy to allow encrypted EBS volumes​

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:Decrypt",
            "kms:GenerateDataKeyWithoutPlaintext",
            "kms:Encrypt",
            "kms:DescribeKey",
            "kms:CreateGrant",
            "ec2:DetachVolume",
            "ec2:AttachVolume",
            "ec2:DeleteSnapshot",
            "ec2:DeleteTags",
            "ec2:CreateTags",
            "ec2:CreateVolume",
            "ec2:DeleteVolume",
            "ec2:CreateSnapshot"
          ],
          "Resource": [
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*",
            "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeInstances",
            "ec2:DescribeTags",
            "ec2:DescribeVolumes",
            "ec2:DescribeSnapshots"
          ],
          "Resource": "*"
        }
      ]
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html index 8d31b106994..6ba95be9981 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html @@ -5,13 +5,13 @@ Creating an Azure Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating an Azure Cluster

    In this section, you'll learn how to install an RKE Kubernetes cluster in Azure through Rancher.

    First, you will set up your Azure cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in Azure.

    Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    Warning: When the Rancher RKE cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows:

    • Terminate the SSL/TLS on the internal load balancer
    • Use the L7 load balancer

    For more information, refer to the documentation on Azure load balancer limitations.

    For more information on configuring the Kubernetes cluster that Rancher will install on the Azure nodes, refer to the RKE cluster configuration reference.

    For more information on configuring Azure node templates, refer to the Azure node template configuration reference.

    Preparation in Azure

    Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription.

    To do this, we will first create a new Azure service principal (SP) in Azure Active Directory (AD), which, in Azure, is an application user who has permission to manage Azure resources.

    The following is a template az cli script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope:

    az ad sp create-for-rbac \
      --name="<Rancher ServicePrincipal name>" \
      --role="Contributor" \
      --scopes="/subscriptions/<subscription Id>"

    The creation of this service principal returns three pieces of identification information, The application ID, also called the client ID, The client secret, and The tenant ID. This information will be used when you create a node template for Azure.

    Creating an Azure Cluster

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select Azure.
    5. Enter your Azure credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for Azure will allow Rancher to provision new nodes in Azure. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for Azure. For help filling out the form, refer to Azure Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in Azure.

    1. From the Clusters page, click Add Cluster.
    2. Choose Azure.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices, see this section.
    7. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html index 5d4a78b1bfe..b8a89e887eb 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html @@ -5,13 +5,13 @@ Creating Credentials in the vSphere Console | Rancher Manager - +
    Version: v2.0-v2.4

    Creating Credentials in the vSphere Console

    This section describes how to create a vSphere username and password. You will need to provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere.

    The following table lists the permissions required for the vSphere user account:

    Privilege GroupOperations
    DatastoreAllocateSpace
    Browse
    FileManagement (Low level file operations)
    UpdateVirtualMachineFiles
    UpdateVirtualMachineMetadata
    NetworkAssign
    ResourceAssignVMToPool
    Virtual MachineConfig (All)
    GuestOperations (All)
    Interact (All)
    Inventory (All)
    Provisioning (All)

    The following steps create a role with the required privileges and then assign it to a new user in the vSphere console:

    1. From the vSphere console, go to the Administration page.

    2. Go to the Roles tab.

    3. Create a new role. Give it a name and select the privileges listed in the permissions table above.

    4. Go to the Users and Groups tab.

    5. Create a new user. Fill out the form and then click OK. Make sure to note the username and password, because you will need it when configuring node templates in Rancher.

    6. Go to the Global Permissions tab.

    7. Create a new Global Permission. Add the user you created earlier and assign it the role you created earlier. Click OK.

    Result: You now have credentials that Rancher can use to manipulate vSphere resources.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html index 7ed67f7e9b9..d8aca34618d 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html @@ -5,13 +5,13 @@ Provisioning Kubernetes Clusters in vSphere | Rancher Manager - +
    Version: v2.0-v2.4

    Provisioning Kubernetes Clusters in vSphere

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

    First, you will set up your vSphere cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision nodes in vSphere.

    Then you will create a vSphere cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    For details on configuring the vSphere node template, refer to the vSphere node template configuration reference.

    For details on configuring RKE Kubernetes clusters in Rancher, refer to the cluster configuration reference.

    Preparation in vSphere

    This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters.

    The node templates are documented and tested with the vSphere Web Services API version 6.5.

    Create Credentials in vSphere​

    Before proceeding to create a cluster, you must ensure that you have a vSphere user with sufficient permissions. When you set up a node template, the template will need to use these vSphere credentials.

    Refer to this how-to guide for instructions on how to create a user in vSphere with the required permissions. These steps result in a username and password that you will need to provide to Rancher, which allows Rancher to provision resources in vSphere.

    Network Permissions​

    It must be ensured that the hosts running the Rancher server are able to establish the following network connections:

    • To the vSphere API on the vCenter server (usually port 443/TCP).
    • To the Host API (port 443/TCP) on all ESXi hosts used to instantiate virtual machines for the clusters (only required with Rancher before v2.3.3 or when using the ISO creation method in later versions).
    • To port 22/TCP and 2376/TCP on the created VMs

    See Node Networking Requirements for a detailed list of port requirements applicable for creating nodes on an infrastructure provider.

    Valid ESXi License for vSphere API Access​

    The free ESXi license does not support API access. The vSphere servers must have a valid or evaluation ESXi license.

    VM-VM Affinity Rules for Clusters with DRS​

    If you have a cluster with DRS enabled, setting up VM-VM Affinity Rules is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate ESXi hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes.

    Creating a vSphere Cluster​

    The a vSphere cluster is created in Rancher depends on the Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select vSphere.
    5. Enter your vSphere credentials. For help, refer to Account Access in the configuration reference for your Rancher version.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for vSphere will allow Rancher to provision new nodes in vSphere. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for vSphere. For help filling out the form, refer to the vSphere node template configuration reference. Refer to the newest version of the configuration reference that is less than or equal to your Rancher version:

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in vSphere.

    1. Navigate to Clusters in the Global view.
    2. Click Add Cluster and select the vSphere infrastructure provider.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. If you want to dynamically provision persistent storage or other infrastructure later, you will need to enable the vSphere cloud provider by modifying the cluster YAML file. For details, refer to this section.
    7. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to the nodes, see this section.
    8. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    • Provision Storage: For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html index 0f91ceb41e8..b6b76000b73 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html @@ -5,13 +5,13 @@ Configuration for Storage Classes in Azure | Rancher Manager - +
    Version: v2.0-v2.4

    Configuration for Storage Classes in Azure

    If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster.

    In order to have the Azure platform create the required storage resources, follow these steps:

    1. Configure the Azure cloud provider.

    2. Configure kubectl to connect to your cluster.

    3. Copy the ClusterRole and ClusterRoleBinding manifest for the service account:

      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: system:azure-cloud-provider
      rules:
      - apiGroups: ['']
        resources: ['secrets']
        verbs:     ['get','create']
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: system:azure-cloud-provider
      roleRef:
        kind: ClusterRole
        apiGroup: rbac.authorization.k8s.io
        name: system:azure-cloud-provider
      subjects:
      - kind: ServiceAccount
        name: persistent-volume-binder
        namespace: kube-system

    4. Create these in your cluster using one of the follow command.

      # kubectl create -f <MANIFEST>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html index 1e21c816017..4ca6890aefa 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html @@ -5,13 +5,13 @@ Networking Requirements for Host Gateway (L2bridge) | Rancher Manager - +
    Version: v2.0-v2.4

    Networking Requirements for Host Gateway (L2bridge)

    This section describes how to configure custom Windows clusters that are using Host Gateway (L2bridge) mode.

    Disabling Private IP Address Checks​

    If you are using Host Gateway (L2bridge) mode and hosting your nodes on any of the cloud services listed below, you must disable the private IP address checks for both your Linux or Windows hosts on startup. To disable this check for each node, follow the directions provided by each service below.

    ServiceDirections to disable private IP address checks
    Amazon EC2Disabling Source/Destination Checks
    Google GCEEnabling IP Forwarding for Instances (By default, a VM cannot forward a packet originated by another VM)
    Azure VMEnable or Disable IP Forwarding

    Cloud-hosted VM Routes Configuration​

    If you are using the Host Gateway (L2bridge) backend of Flannel, all containers on the same node belong to a private subnet, and traffic routes from a subnet on one node to a subnet on another node through the host network.

    • When worker nodes are provisioned on AWS, virtualization clusters, or bare metal servers, make sure they belong to the same layer 2 subnet. If the nodes don't belong to the same layer 2 subnet, host-gw networking will not work.

    • When worker nodes are provisioned on GCE or Azure, they are not on the same layer 2 subnet. Nodes on GCE and Azure belong to a routable layer 3 network. Follow the instructions below to configure GCE and Azure so that the cloud network knows how to route the host subnets on each node.

    To configure host subnet routing on GCE or Azure, first run the following command to find out the host subnets on each worker node:

    kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR

    Then follow the instructions for each cloud provider to configure routing rules for each node:

    ServiceInstructions
    Google GCEFor GCE, add a static route for each node: Adding a Static Route.
    Azure VMFor Azure, create a routing table: Custom Routes: User-defined.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/v2.1-v2.2.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/v2.1-v2.2.html index eb0e181967d..14e02218462 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/v2.1-v2.2.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/v2.1-v2.2.html @@ -5,13 +5,13 @@ v2.1.x and v2.2.x Windows Documentation (Experimental) | Rancher Manager - +
    Version: v2.0-v2.4

    v2.1.x and v2.2.x Windows Documentation (Experimental)

    Available from v2.1.0 to v2.1.9 and v2.2.0 to v2.2.3

    This section describes how to provision Windows clusters in Rancher v2.1.x and v2.2.x. If you are using Rancher v2.3.0 or later, please refer to the new documentation for v2.3.0 or later.

    When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to provision the Kubernetes cluster on your existing infrastructure.

    You can provision a custom Windows cluster using Rancher by using a mix of Linux and Windows hosts as your cluster nodes.

    Important: In versions of Rancher before v2.3, support for Windows nodes is experimental. Therefore, it is not recommended to use Windows nodes for production environments if you are using Rancher before v2.3.

    This guide walks you through create of a custom cluster that includes three nodes:

    • A Linux node, which serves as a Kubernetes control plane node
    • Another Linux node, which serves as a Kubernetes worker used to support Ingress for the cluster
    • A Windows node, which is assigned the Kubernetes worker role and runs your Windows containers

    For a summary of Kubernetes features supported in Windows, see Using Windows in Kubernetes.

    OS and Container Requirements​

    • For clusters provisioned with Rancher v2.1.x and v2.2.x, containers must run on Windows Server 1809 or above.
    • You must build containers on a Windows Server core version 1809 or above to run these containers on the same server version.

    Objectives for Creating Cluster with Windows Support​

    When setting up a custom cluster with support for Windows nodes and containers, complete the series of tasks below.

    1. Provision Hosts​

    To begin provisioning a custom cluster with Windows support, prepare your host servers. Provision three nodes according to our requirements—two Linux, one Windows. Your hosts can be:

    • Cloud-hosted VMs
    • VMs from virtualization clusters
    • Bare-metal servers

    The table below lists the Kubernetes node roles you'll assign to each host, although you won't enable these roles until further along in the configuration process—we're just informing you of each node's purpose. The first node, a Linux host, is primarily responsible for managing the Kubernetes control plane, although, in this use case, we're installing all three roles on this node. Node 2 is also a Linux worker, which is responsible for Ingress support. Finally, the third node is your Windows worker, which will run your Windows applications.

    NodeOperating SystemFuture Cluster Role(s)
    Node 1Linux (Ubuntu Server 16.04 recommended)Control plane, etcd, worker
    Node 2Linux (Ubuntu Server 16.04 recommended)Worker (This node is used for Ingress support)
    Node 3Windows (Windows Server core version 1809 or above)Worker

    Requirements​

    • You can view node requirements for Linux and Windows nodes in the installation section.
    • All nodes in a virtualization cluster or a bare metal cluster must be connected using a layer 2 network.
    • To support Ingress, your cluster must include at least one Linux node dedicated to the worker role.
    • Although we recommend the three node architecture listed in the table above, you can add additional Linux and Windows workers to scale up your cluster for redundancy.

    2. Cloud-hosted VM Networking Configuration​

    Note: This step only applies to nodes hosted on cloud-hosted virtual machines. If you're using virtualization clusters or bare-metal servers, skip ahead to Create the Custom Cluster.

    If you're hosting your nodes on any of the cloud services listed below, you must disable the private IP address checks for both your Linux or Windows hosts on startup. To disable this check for each node, follow the directions provided by each service below.

    ServiceDirections to disable private IP address checks
    Amazon EC2Disabling Source/Destination Checks
    Google GCEEnabling IP Forwarding for Instances
    Azure VMEnable or Disable IP Forwarding

    3. Create the Custom Cluster​

    To create a custom cluster that supports Windows nodes, follow the instructions in Creating a Cluster with Custom Nodes, starting from 2. Create the Custom Cluster. While completing the linked instructions, look for steps that requires special actions for Windows nodes, which are flagged with a note. These notes will link back here, to the special Windows instructions listed in the subheadings below.

    Enable the Windows Support Option​

    While choosing Cluster Options, set Windows Support (Experimental) to Enabled.

    After you select this option, resume Creating a Cluster with Custom Nodes from step 6.

    Networking Option​

    When choosing a network provider for a cluster that supports Windows, the only option available is Flannel, as host-gw is needed for IP routing.

    If your nodes are hosted by a cloud provider and you want automation support such as load balancers or persistent storage devices, see Selecting Cloud Providers for configuration info.

    Node Configuration​

    The first node in your cluster should be a Linux host that fills the Control Plane role. This role must be fulfilled before you can add Windows hosts to your cluster. At minimum, the node must have this role enabled, but we recommend enabling all three. The following table lists our recommended settings (we'll provide the recommended settings for nodes 2 and 3 later).

    OptionSetting
    Node Operating SystemLinux
    Node Rolesetcd
    Control Plane
    Worker

    When you're done with these configurations, resume Creating a Cluster with Custom Nodes from step 8.

    4. Add Linux Host for Ingress Support​

    After the initial provisioning of your custom cluster, your cluster only has a single Linux host. Add another Linux host, which will be used to support Ingress for your cluster.

    1. Using the content menu, open the custom cluster your created in 2. Create the Custom Cluster.

    2. From the main menu, select Nodes.

    3. Click Edit Cluster.

    4. Scroll down to Node Operating System. Choose Linux.

    5. Select the Worker role.

    6. Copy the command displayed on screen to your clipboard.

    7. Log in to your Linux host using a remote Terminal connection. Run the command copied to your clipboard.

    8. From Rancher, click Save.

    Result: The worker role is installed on your Linux host, and the node registers with Rancher.

    5. Adding Windows Workers​

    You can add Windows hosts to a custom cluster by editing the cluster and choosing the Windows option.

    1. From the main menu, select Nodes.

    2. Click Edit Cluster.

    3. Scroll down to Node Operating System. Choose Windows.

    4. Select the Worker role.

    5. Copy the command displayed on screen to your clipboard.

    6. Log in to your Windows host using your preferred tool, such as Microsoft Remote Desktop. Run the command copied to your clipboard in the Command Prompt (CMD).

    7. From Rancher, click Save.

    8. Optional: Repeat these instruction if you want to add more Windows nodes to your cluster.

    Result: The worker role is installed on your Windows host, and the node registers with Rancher.

    6. Cloud-hosted VM Routes Configuration​

    In Windows clusters, containers communicate with each other using the host-gw mode of Flannel. In host-gw mode, all containers on the same node belong to a private subnet, and traffic routes from a subnet on one node to a subnet on another node through the host network.

    • When worker nodes are provisioned on AWS, virtualization clusters, or bare metal servers, make sure they belong to the same layer 2 subnet. If the nodes don't belong to the same layer 2 subnet, host-gw networking will not work.

    • When worker nodes are provisioned on GCE or Azure, they are not on the same layer 2 subnet. Nodes on GCE and Azure belong to a routable layer 3 network. Follow the instructions below to configure GCE and Azure so that the cloud network knows how to route the host subnets on each node.

    To configure host subnet routing on GCE or Azure, first run the following command to find out the host subnets on each worker node:

    kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR

    Then follow the instructions for each cloud provider to configure routing rules for each node:

    ServiceInstructions
    Google GCEFor GCE, add a static route for each node: Adding a Static Route.
    Azure VMFor Azure, create a routing table: Custom Routes: User-defined.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html index 7dfb1550649..7654759d407 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html @@ -5,13 +5,13 @@ Node Requirements for Rancher Managed Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Node Requirements for Rancher Managed Clusters

    This page describes the requirements for the Rancher managed Kubernetes clusters where your apps and services will be installed. These downstream clusters should be separate from the three-node cluster running Rancher.

    If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the installation section.

    Operating Systems and Container Runtime Requirements​

    Rancher should work with any modern Linux distribution and any modern Docker version. Linux is required for the etcd and controlplane nodes of all downstream clusters. Worker nodes may run Linux or Windows Server. The capability to use Windows worker nodes in downstream clusters was added in Rancher v2.3.0.

    For details on which OS and Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    All supported operating systems are 64-bit x86.

    If you plan to use ARM64, see Running on ARM64 (Experimental).

    For information on how to install Docker, refer to the official Docker documentation.

    Oracle Linux and RHEL Derived Linux Nodes​

    Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.

    SUSE Linux Nodes​

    SUSE Linux may have a firewall that blocks all ports by default. In that situation, follow these steps to open the ports needed for adding a host to a custom cluster.

    Flatcar Container Linux Nodes​

    When Launching Kubernetes with Rancher using Flatcar Container Linux nodes, it is required to use the following configuration in the Cluster Config File

    rancher_kubernetes_engine_config:
      network:
        plugin: canal
        options:
          canal_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds
          flannel_backend_type: vxlan

      services:
        kube-controller:
          extra_args:
            flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/

    It is also required to enable the Docker service, you can enable the Docker service using the following command:

    systemctl enable docker.service

    The Docker service is enabled automatically when using Node Drivers.

    Windows Nodes​

    Windows worker nodes can be used as of Rancher v2.3.0

    Nodes with Windows Server must run Docker Enterprise Edition.

    Windows nodes can be used for worker nodes only. See Configuring Custom Clusters for Windows

    Hardware Requirements​

    The hardware requirements for nodes with the worker role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory.

    Regarding CPU and memory, it is recommended that the different planes of Kubernetes clusters (etcd, controlplane, and workers) should be hosted on different nodes so that they can scale separately from each other.

    For hardware recommendations for large Kubernetes clusters, refer to the official Kubernetes documentation on building large clusters.

    For hardware recommendations for etcd clusters in production, refer to the official etcd documentation.

    Networking Requirements​

    For a production cluster, we recommend that you restrict traffic by opening only the ports defined in the port requirements below.

    The ports required to be open are different depending on how the user cluster is launched. Each of the sections below list the ports that need to be opened for different cluster creation options.

    For a breakdown of the port requirements for etcd nodes, controlplane nodes, and worker nodes in a Kubernetes cluster, refer to the port requirements for the Rancher Kubernetes Engine.

    Details on which ports are used in each situation are found under Downstream Cluster Port Requirements.

    Optional: Security Considerations​

    If you want to provision a Kubernetes cluster that is compliant with the CIS (Center for Internet Security) Kubernetes Benchmark, we recommend to following our hardening guide to configure your nodes before installing Kubernetes.

    For more information on the hardening guide and details on which version of the guide corresponds to your Rancher and Kubernetes versions, refer to the security section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html index 44de5959304..7efd82767e3 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html @@ -5,14 +5,14 @@ Creating an AKS Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating an AKS Cluster

    You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS).

    Prerequisites in Microsoft Azure​

    Note Deploying to AKS will incur charges.

    To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the AKS documentation.

    Before creating the service principal, you need to obtain the following information from the Microsoft Azure Portal:

    • Your subscription ID
    • Your tenant ID
    • An app ID (also called a client ID)
    • Client secret
    • A resource group

    The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal.

    Setting Up the Service Principal with the Azure Command Line Tool​

    You can create the service principal by running this command:

    az ad sp create-for-rbac --skip-assignment

    The result should show information about the new service principal:

    {
      "appId": "xxxx--xxx",
      "displayName": "<SERVICE-PRINCIPAL-NAME>",
      "name": "http://<SERVICE-PRINCIPAL-NAME>",
      "password": "<SECRET>",
      "tenant": "<TENANT NAME>"
    }

    You also need to add roles to the service principal so that it has privileges for communication with the AKS API. It also needs access to create and list virtual networks.

    Below is an example command for assigning the Contributor role to a service principal. Contributors can manage anything on AKS but cannot give access to others:

    az role assignment create \
      --assignee $appId \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    You can also create the service principal and give it Contributor privileges by combining the two commands into one. In this command, the scope needs to provide a full path to an Azure resource:

    az ad sp create-for-rbac \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    Setting Up the Service Principal from the Azure Portal​

    You can also follow these instructions to set up a service principal and give it role-based access from the Azure Portal.

    1. Go to the Microsoft Azure Portal home page.

    2. Click Azure Active Directory.

    3. Click App registrations.

    4. Click New registration.

    5. Enter a name. This will be the name of your service principal.

    6. Optional: Choose which accounts can use the service principal.

    7. Click Register.

    8. You should now see the name of your service principal under Azure Active Directory > App registrations.

    9. Click the name of your service principal. Take note of the tenant ID and application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click Certificates & secrets.

    10. Click New client secret.

    11. Enter a short description, pick an expiration time, and click Add. Take note of the client secret so that you can use it when provisioning the AKS cluster.

    Result: You have created a service principal and you should be able to see it listed in the Azure Active Directory section under App registrations. You still need to give the service principal access to AKS.

    To give role-based access to your service principal,

    1. Click All Services in the left navigation bar. Then click Subscriptions.

    2. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster.

    3. Click Access Control (IAM).

    4. In the Add role assignment section, click Add.

    5. In the Role field, select a role that will have access to AKS. For example, you can use the Contributor role, which has permission to manage everything except for giving access to other users.

    6. In the Assign access to field, select Azure AD user, group, or service principal.

    7. In the Select field, select the name of your service principal and click Save.

    Result: Your service principal now has access to AKS.

    Create the AKS Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. From the Clusters page, click Add Cluster.

    2. Choose Azure Kubernetes Service.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Use your subscription ID, tenant ID, app ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:

    • App ID and tenant ID: To get the app ID and tenant ID, you can go to the Azure Portal, then click Azure Active Directory, then click App registrations, then click the name of the service principal. The app ID and tenant ID are both on the app registration detail page.
    • Client secret: If you didn't copy the client secret when creating the service principal, you can get a new one if you go to the app registration detail page, then click Certificates & secrets, then click New client secret.
    • Subscription ID: You can get the subscription ID is available in the portal from All services > Subscriptions.

    1. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options.

    2. Complete the Account Access form using the output from your Service Principal. This information is used to authenticate with Azure.

    3. Use Nodes to provision each node in your cluster and choose a geographical region.

      [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys)

    4. Click Create.


    5. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html index ee1d43a4506..5fabb13b9bb 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html @@ -5,14 +5,14 @@ Creating an Aliyun ACK Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating an Aliyun ACK Cluster

    Available as of v2.2.0

    You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the cluster driver for ACK, but by default, this cluster driver is inactive. In order to launch ACK clusters, you will need to enable the ACK cluster driver. After enabling the cluster driver, you can start provisioning ACK clusters.

    Prerequisites​

    Note Deploying to ACK will incur charges.

    1. In Aliyun, activate the following services in their respective consoles.

    2. Make sure that the account you will be using to create the ACK cluster has the appropriate permissions. Referring to the official Alibaba Cloud documentation about Role authorization and Use the Container Service console as a RAM user for details.

    3. In Alibaba Cloud, create an access key.

    4. In Alibaba Cloud, create an SSH key pair. This key is used to access nodes in the Kubernetes cluster.

    Create an ACK Cluster​

    1. From the Clusters page, click Add Cluster.

    2. Choose Alibaba ACK.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Configure Account Access for the ACK cluster. Choose the geographical region in which to build your cluster, and input the access key that was created as part of the prerequisite steps.

    6. Click Next: Configure Cluster, then choose cluster type, the version of Kubernetes and the availability zone.

    7. If you choose Kubernetes as the cluster type, Click Next: Configure Master Nodes, then complete the Master Nodes form.

    8. Click Next: Configure Worker Nodes, then complete the Worker Nodes form.

    9. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html index 0440ba33a02..cfe13ab319b 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html @@ -5,14 +5,14 @@ Creating a GKE Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating a GKE Cluster

    Prerequisites in Google Kubernetes Engine​

    Note Deploying to GKE will incur charges.

    Create a service account using Google Kubernetes Engine. GKE uses this account to operate your cluster. Creating this account also generates a private key used for authentication.

    The service account requires the following roles:

    • Compute Viewer: roles/compute.viewer
    • Project Viewer: roles/viewer
    • Kubernetes Engine Admin: roles/container.admin
    • Service Account User: roles/iam.serviceAccountUser

    Google Documentation: Creating and Enabling Service Accounts

    Create the GKE Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. From the Clusters page, click Add Cluster.

    2. Choose Google Kubernetes Engine.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Either paste your service account private key in the Service Account text box or Read from a file. Then click Next: Configure Nodes.

      Note: After submitting your private key, you may have to enable the Google Kubernetes Engine API. If prompted, browse to the URL displayed in the Rancher UI to enable the API.

    6. Select your Cluster Options

    7. Customize your Node Options

      • Enabling the Auto Upgrade feature for Nodes is not recommended.

    8. Select your Security Options

    9. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html index a6289a7b78b..d0a5f233264 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html @@ -5,14 +5,14 @@ Creating a Huawei CCE Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating a Huawei CCE Cluster

    Available as of v2.2.0

    You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the cluster driver for CCE, but by default, this cluster driver is inactive. In order to launch CCE clusters, you will need to enable the CCE cluster driver. After enabling the cluster driver, you can start provisioning CCE clusters.

    Prerequisites in Huawei​

    Note Deploying to CCE will incur charges.

    1. Find your project ID in Huawei CCE portal. See the CCE documentation on how to manage your projects.

    2. Create an Access Key ID and Secret Access Key.

    Limitations​

    Huawei CCE service doesn't support the ability to create clusters with public access through their API. You are required to run Rancher in the same VPC as the CCE clusters that you want to provision.

    Create the CCE Cluster​

    1. From the Clusters page, click Add Cluster.
    2. Choose Huawei CCE.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Enter Project Id, Access Key ID as Access Key and Secret Access Key Secret Key. Then Click Next: Configure cluster. Fill in the cluster configuration. For help filling out the form, refer to Huawei CCE Configuration.
    6. Fill the following node configuration of the cluster. For help filling out the form, refer to Node Configuration.
    7. Click Create to create the CCE cluster.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Huawei CCE Configuration​

    SettingsDescription
    Cluster TypeWhich type or node you want to include into the cluster, VirtualMachine or BareMetal.
    DescriptionThe description of the cluster.
    Master VersionThe Kubernetes version.
    Management Scale CountThe max node count of the cluster. The options are 50, 200 and 1000. The larger of the scale count, the more the cost.
    High AvailabilityEnable master node high availability. The cluster with high availability enabled will have more cost.
    Container Network ModeThe network mode used in the cluster. overlay_l2 and vpc-router is supported in VirtualMachine type and underlay_ipvlan is supported in BareMetal type
    Container Network CIDRNetwork CIDR for the cluster.
    VPC NameThe VPC name which the cluster is going to deploy into. Rancher will create one if it is blank.
    Subnet NameThe Subnet name which the cluster is going to deploy into. Rancher will create one if it is blank.
    External ServerThis option is reserved for the future we can enable CCE cluster public access via API. For now, it is always disabled.
    Cluster LabelThe labels for the cluster.
    Highway SubnetThis option is only supported in BareMetal type. It requires you to select a VPC with high network speed for the bare metal machines.

    Note: If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    Node Configuration​

    SettingsDescription
    ZoneThe available zone at where the node(s) of the cluster is deployed.
    Billing ModeThe bill mode for the cluster node(s). In VirtualMachine type, only Pay-per-use is supported. in BareMetal, you can choose Pay-per-use or Yearly/Monthly.
    Validity PeriodThis option only shows in Yearly/Monthly bill mode. It means how long you want to pay for the cluster node(s).
    Auto RenewThis option only shows in Yearly/Monthly bill mode. It means that the cluster node(s) will renew the Yearly/Monthly payment automatically or not.
    Data Volume TypeData volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Data Volume SizeData volume size for the cluster node(s)
    Root Volume TypeRoot volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Root Volume SizeRoot volume size for the cluster node(s)
    Node FlavorThe node flavor of the cluster node(s). The flavor list in Rancher UI is fetched from Huawei Cloud. It includes all the supported node flavors.
    Node CountThe node count of the cluster
    Node Operating SystemThe operating system for the cluster node(s). Only EulerOS 2.2 and CentOS 7.4 are supported right now.
    SSH Key NameThe ssh key for the cluster node(s)
    EIPThe public IP options for the cluster node(s). Disabled means that the cluster node(s) are not going to bind a public IP. Create EIP means that the cluster node(s) will bind one or many newly created Eips after provisioned and more options will be shown in the UI to set the to-create EIP parameters. And Select Existed EIP means that the node(s) will bind to the EIPs you select.
    EIP CountThis option will only be shown when Create EIP is selected. It means how many EIPs you want to create for the node(s).
    EIP TypeThis option will only be shown when Create EIP is selected. The options are 5_bgp and 5_sbgp.
    EIP Share TypeThis option will only be shown when Create EIP is selected. The only option is PER.
    EIP Charge ModeThis option will only be shown when Create EIP is selected. The options are pay by BandWidth and pay by Traffic.
    EIP Bandwidth SizeThis option will only be shown when Create EIP is selected. The BandWidth of the EIPs.
    Authentication ModeIt means enabling RBAC or also enabling Authenticating Proxy. If you select Authenticating Proxy, the certificate which is used for authenticating proxy will be also required.
    Node LabelThe labels for the cluster node(s).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html index 12b4098b1c6..aa7372c8346 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html @@ -5,14 +5,14 @@ Creating a Tencent TKE Cluster | Rancher Manager - +
    Version: v2.0-v2.4

    Creating a Tencent TKE Cluster

    Available as of v2.2.0

    You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the cluster driver for TKE, but by default, this cluster driver is inactive. In order to launch TKE clusters, you will need to enable the TKE cluster driver. After enabling the cluster driver, you can start provisioning TKE clusters.

    Prerequisites in Tencent​

    Note Deploying to TKE will incur charges.

    1. Make sure that the account you will be using to create the TKE cluster has the appropriate permissions by referring to the Cloud Access Management documentation for details.

    2. Create a Cloud API Secret ID and Secret Key.

    3. Create a Private Network and Subnet in the region that you want to deploy your Kubernetes cluster.

    4. Create a SSH key pair. This key is used to access the nodes in the Kubernetes cluster.

    Create a TKE Cluster​

    1. From the Clusters page, click Add Cluster.

    2. Choose Tencent TKE.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Configure Account Access for the TKE cluster. Complete each drop-down and field using the information obtained in Prerequisites.

      OptionDescription
      RegionFrom the drop-down chooses the geographical region in which to build your cluster.
      Secret IDEnter the Secret ID that you obtained from the Tencent Cloud Console.
      Secret KeyEnter the Secret key that you obtained from Tencent Cloud Console.

    6. Click Next: Configure Cluster to set your TKE cluster configurations.

      OptionDescription
      Kubernetes VersionThe TKE only supports Kubernetes version 1.10.5 now.
      Node CountEnter the amount of worker node you want to purchase for your Kubernetes cluster, up to 100.
      VPCSelect the VPC name that you have created in the Tencent Cloud Console.
      Container Network CIDREnter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16.

      Note: If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that as of Rancher v2.3.0, cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    7. Click Next: Select Instance Type to choose the instance type that will use for your TKE cluster.

      OptionDescription
      Availability ZoneChoose the availability zone of the VPC region.
      SubnetSelect the Subnet that you have created within the VPC, and add a new one if you don't have it in the chosen availability zone.
      Instance TypeFrom the drop-down chooses the VM instance type that you want to use for the TKE cluster, default to S2.MEDIUM4 (CPU 2 Memory 4 GiB).

    8. Click Next: Configure Instance to configure the VM instance that will use for your TKE cluster.

      OptionDescription
      Operating SystemThe name of the operating system, currently supports Centos7.2x86_64 or ubuntu16.04.1 LTSx86_64
      Security GroupSecurity group ID, default does not bind any security groups.
      Root Disk TypeSystem disk type. System disk type restrictions are detailed in the CVM instance configuration.
      Root Disk SizeSystem disk size. Linux system adjustment range is 20 - 50G, step size is 1.
      Data Disk TypeData disk type, default value to the SSD cloud drive
      Data Disk SizeData disk size (GB), the step size is 10
      Band Width TypeType of bandwidth, PayByTraffic or PayByHour
      Band WidthPublic network bandwidth (Mbps)
      Key PairKey id, after associating the key can be used to logging to the VM node

    9. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html index 2dd062b20b4..5f55a7a2f7d 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html @@ -5,13 +5,13 @@ ConfigMaps | Rancher Manager - +
    Version: v2.0-v2.4

    ConfigMaps

    While most types of Kubernetes secrets store sensitive information, ConfigMaps store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect).

    ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount.

    Note: ConfigMaps can only be applied to namespaces and not projects.

    1. From the Global view, select the project containing the namespace that you want to add a ConfigMap to.

    2. From the main menu, select Resources > Config Maps. Click Add Config Map.

    3. Enter a Name for the Config Map.

      Note: Kubernetes classifies ConfigMaps as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace.

    4. Select the Namespace you want to add Config Map to. You can also add a new namespace on the fly by clicking Add to a new namespace.

    5. From Config Map Values, click Add Config Map Value to add a key value pair to your ConfigMap. Add as many values as you need.

    6. Click Save.

      Note: Don't use ConfigMaps to store sensitive data use a secret.

      Tip: You can add multiple key value pairs to the ConfigMap by copying and pasting.

    Result: Your ConfigMap is added to the namespace. You can view it in the Rancher UI from the Resources > Config Maps view.

    What's Next?​

    Now that you have a ConfigMap added to a namespace, you can add it to a workload that you deploy from the namespace of origin. You can use the ConfigMap to specify information for you application to consume, such as:

    • Application environment variables.
    • Specifying parameters for a Volume mounted to the workload.

    For more information on adding ConfigMaps to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html index 94a9d0f5e63..e53154b58ad 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html @@ -5,14 +5,14 @@ Service Discovery | Rancher Manager - +
    Version: v2.0-v2.4

    Service Discovery

    For every workload created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention: <workload>.<namespace>.svc.cluster.local.

    However, you also have the option of creating additional Service Discovery records. You can use these additional records so that a given namespace resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create.

    1. From the Global view, open the project that you want to add a DNS record to.

    2. Click Resources in the main navigation bar. Click the Service Discovery tab. (In versions before v2.3.0, just click the Service Discovery tab.) Then click Add Record.

    3. Enter a Name for the DNS record. This name is used for DNS resolution.

    4. Select a Namespace from the drop-down list. Alternatively, you can create a new namespace on the fly by clicking Add to a new namespace.

    5. Select one of the Resolves To options to route requests to the DNS record.

      1. One or more external IP addresses

        Enter an IP address in the Target IP Addresses field. Add more IP addresses by clicking Add Target IP.

      2. An external hostname

        Enter a Target Hostname.

      3. Alias of another DNS record's value

        Click Add Target Record and select another DNS record from the Value drop-down.

      4. One or more workloads

        Click Add Target Workload and select another workload from the Value drop-down.

      5. The set of pods which match a selector

        Enter key value pairs of label selectors to create a record for all pods that match your parameters.

    6. Click Create

    Result: A new DNS record is created.

    • You can view the record by from the project's Service Discovery tab.
    • When you visit the new DNS name for the new record that you created (<recordname>.<namespace>.svc.cluster.local), it resolves the chosen namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html index 9aa6e6aaac6..53b49958d1b 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html @@ -5,13 +5,13 @@ Encrypting HTTP Communication | Rancher Manager - +
    Version: v2.0-v2.4

    Encrypting HTTP Communication

    When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by navigating to its project or namespace, and then uploading the certificate. You can then add the certificate to the ingress deployment.

    Add SSL certificates to either projects, namespaces, or both. A project scoped certificate will be available in all its namespaces.

    Prerequisites: You must have a TLS private key and certificate available to upload.

    1. From the Global view, select the project where you want to deploy your ingress.

    2. From the main menu, select Resources > Secrets > Certificates. Click Add Certificate. (For Rancher before v2.3, click Resources > Certificates.)

    3. Enter a Name for the certificate.

      Note: Kubernetes classifies SSL certificates as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your SSL certificate must have a unique name among the other certificates, registries, and secrets within your project/workspace.

    4. Select the Scope of the certificate.

      • Available to all namespaces in this project: The certificate is available for any deployment in any namespaces in the project.

      • Available to a single namespace: The certificate is only available for the deployments in one namespace. If you choose this option, select a Namespace from the drop-down list or click Add to a new namespace to add the certificate to a namespace you create on the fly.

    5. From Private Key, either copy and paste your certificate's private key into the text box (include the header and footer), or click Read from a file to browse to the private key on your file system. If possible, we recommend using Read from a file to reduce likelihood of error.

      Private key files end with an extension of .key.

    6. From Certificate, either copy and paste your certificate into the text box (include the header and footer), or click Read from a file to browse to the certificate on your file system. If possible, we recommend using Read from a file to reduce likelihood of error.

      Certificate files end with an extension of .crt.

    Result: Your certificate is added to the project or namespace. You can now add it to deployments.

    • If you added an SSL certificate to the project, the certificate is available for deployments created in any project namespace.
    • If you added an SSL certificate to a namespace, the certificate is available only for deployments in that namespace.
    • Your certificate is added to the Resources > Secrets > Certificates view. (For Rancher before v2.3, it is added to Resources > Certificates.)

    What's Next?​

    Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see Adding Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html index 1c08e135aca..b559767d627 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html @@ -5,13 +5,13 @@ Background Information on HPAs | Rancher Manager - +
    Version: v2.0-v2.4

    Background Information on HPAs

    The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down. This section provides explanation on how HPA works with Kubernetes.

    Why Use Horizontal Pod Autoscaler?​

    Using HPA, you can automatically scale the number of pods within a replication controller, deployment, or replica set up or down. HPA automatically scales the number of pods that are running for maximum efficiency. Factors that affect the number of pods include:

    • A minimum and maximum number of pods allowed to run, as defined by the user.
    • Observed CPU/memory use, as reported in resource metrics.
    • Custom metrics provided by third-party metrics application like Prometheus, Datadog, etc.

    HPA improves your services by:

    • Releasing hardware resources that would otherwise be wasted by an excessive number of pods.
    • Increase/decrease performance as needed to accomplish service level agreements.

    How HPA Works​

    HPA Schema

    HPA is implemented as a control loop, with a period controlled by the kube-controller-manager flags below:

    FlagDefaultDescription
    --horizontal-pod-autoscaler-sync-period30sHow often HPA audits resource/custom metrics in a deployment.
    --horizontal-pod-autoscaler-downscale-delay5m0sFollowing completion of a downscale operation, how long HPA must wait before launching another downscale operations.
    --horizontal-pod-autoscaler-upscale-delay3m0sFollowing completion of an upscale operation, how long HPA must wait before launching another upscale operation.

    For full documentation on HPA, refer to the Kubernetes Documentation.

    Horizontal Pod Autoscaler API Objects​

    HPA is an API resource in the Kubernetes autoscaling API group. The current stable version is autoscaling/v1, which only includes support for CPU autoscaling. To get additional support for scaling based on memory and custom metrics, use the beta version instead: autoscaling/v2beta1.

    For more information about the HPA API object, see the HPA GitHub Readme.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/hpa-for-rancher-before-2.0.7.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/hpa-for-rancher-before-2.0.7.html index 78ad4303678..242ce52dc20 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/hpa-for-rancher-before-2.0.7.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/hpa-for-rancher-before-2.0.7.html @@ -5,13 +5,13 @@ Manual HPA Installation for Clusters Created Before Rancher v2.0.7 | Rancher Manager - +
    Version: v2.0-v2.4

    Manual HPA Installation for Clusters Created Before Rancher v2.0.7

    This section describes how to manually install HPAs for clusters created with Rancher before v2.0.7. This section also describes how to configure your HPA to scale up or down, and how to assign roles to your HPA.

    Before you can use HPA in your Kubernetes cluster, you must fulfill some requirements.

    Requirements​

    Be sure that your Kubernetes cluster services are running with these flags at minimum:

    • kube-api: requestheader-client-ca-file

    • kubelet: read-only-port at 10255

    • kube-controller: Optional, just needed if distinct values than default are required.

      • horizontal-pod-autoscaler-downscale-delay: "5m0s"
      • horizontal-pod-autoscaler-upscale-delay: "3m0s"
      • horizontal-pod-autoscaler-sync-period: "30s"

    For an RKE Kubernetes cluster definition, add this snippet in the services section. To add this snippet using the Rancher v2.0 UI, open the Clusters view and select ⋮ > Edit for the cluster in which you want to use HPA. Then, from Cluster Options, click Edit as YAML. Add the following snippet to the services section:

    services:
    ...
      kube-api:
        extra_args:
          requestheader-client-ca-file: "/etc/kubernetes/ssl/kube-ca.pem"
      kube-controller:
        extra_args:
          horizontal-pod-autoscaler-downscale-delay: "5m0s"
          horizontal-pod-autoscaler-upscale-delay: "1m0s"
          horizontal-pod-autoscaler-sync-period: "30s"
      kubelet:
        extra_args:
          read-only-port: 10255

    Once the Kubernetes cluster is configured and deployed, you can deploy metrics services.

    Note: kubectl command samples in the sections that follow were tested in a cluster running Rancher v2.0.6 and Kubernetes v1.10.1.

    Configuring HPA to Scale Using Resource Metrics​

    To create HPA resources based on resource metrics such as CPU and memory use, you need to deploy the metrics-server package in the kube-system namespace of your Kubernetes cluster. This deployment allows HPA to consume the metrics.k8s.io API.

    Prerequisite: You must be running kubectl 1.8 or later.

    1. Connect to your Kubernetes cluster using kubectl.

    2. Clone the GitHub metrics-server repo:

      # git clone https://github.com/kubernetes-incubator/metrics-server

    3. Install the metrics-server package.

      # kubectl create -f metrics-server/deploy/1.8+/

    4. Check that metrics-server is running properly. Check the service pod and logs in the kube-system namespace.

    5. Check the service pod for a status of running. Enter the following command:

      # kubectl get pods -n kube-system

      Then check for the status of running.

      NAME                                  READY     STATUS    RESTARTS   AGE
      ...
      metrics-server-6fbfb84cdd-t2fk9       1/1       Running   0          8h
      ...

    6. Check the service logs for service availability. Enter the following command:

      # kubectl -n kube-system logs metrics-server-6fbfb84cdd-t2fk9

      Then review the log to confirm that the metrics-server package is running.

      Metrics Server Log Output
      I0723 08:09:56.193136       1 heapster.go:71] /metrics-server --source=kubernetes.summary_api:''
      I0723 08:09:56.193574       1 heapster.go:72] Metrics Server version v0.2.1
      I0723 08:09:56.194480       1 configs.go:61] Using Kubernetes client with master "https://10.43.0.1:443" and version
      I0723 08:09:56.194501       1 configs.go:62] Using kubelet port 10255
      I0723 08:09:56.198612       1 heapster.go:128] Starting with Metric Sink
      I0723 08:09:56.780114       1 serving.go:308] Generated self-signed cert (apiserver.local.config/certificates/apiserver.crt, apiserver.local.config/certificates/apiserver.key)
      I0723 08:09:57.391518       1 heapster.go:101] Starting Heapster API server...
      [restful] 2018/07/23 08:09:57 log.go:33: [restful/swagger] listing is available at https:///swaggerapi
      [restful] 2018/07/23 08:09:57 log.go:33: [restful/swagger] https:///swaggerui/ is mapped to folder /swagger-ui/
      I0723 08:09:57.394080       1 serve.go:85] Serving securely on 0.0.0.0:443
    1. Check that the metrics api is accessible from kubectl.

    • If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: https://<RANCHER_URL>/k8s/clusters/<CLUSTER_ID>. Add the suffix /k8s/clusters/<CLUSTER_ID> to API path.

      # kubectl get --raw /k8s/clusters/<CLUSTER_ID>/apis/metrics.k8s.io/v1beta1

      If the API is working correctly, you should receive output similar to the output below.

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"metrics.k8s.io/v1beta1","resources":[{"name":"nodes","singularName":"","namespaced":false,"kind":"NodeMetrics","verbs":["get","list"]},{"name":"pods","singularName":"","namespaced":true,"kind":"PodMetrics","verbs":["get","list"]}]}

    • If you are accessing the cluster directly, enter your Server URL in the kubectl config in the following format: https://<K8s_URL>:6443.

      # kubectl get --raw /apis/metrics.k8s.io/v1beta1

      If the API is working correctly, you should receive output similar to the output below.

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"metrics.k8s.io/v1beta1","resources":[{"name":"nodes","singularName":"","namespaced":false,"kind":"NodeMetrics","verbs":["get","list"]},{"name":"pods","singularName":"","namespaced":true,"kind":"PodMetrics","verbs":["get","list"]}]}

    Assigning Additional Required Roles to Your HPA​

    By default, HPA reads resource and custom metrics with the user system:anonymous. Assign system:anonymous to view-resource-metrics and view-custom-metrics in the ClusterRole and ClusterRoleBindings manifests. These roles are used to access metrics.

    To do it, follow these steps:

    1. Configure kubectl to connect to your cluster.

    2. Copy the ClusterRole and ClusterRoleBinding manifest for the type of metrics you're using for your HPA.

      Resource Metrics: ApiGroups resource.metrics.k8s.io
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: view-resource-metrics
      rules:
      - apiGroups:
          - metrics.k8s.io
        resources:
          - pods
          - nodes
        verbs:
          - get
          - list
          - watch
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: view-resource-metrics
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: view-resource-metrics
      subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: User
          name: system:anonymous
      Custom Metrics: ApiGroups custom.metrics.k8s.io
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: view-custom-metrics
      rules:
      - apiGroups:
          - custom.metrics.k8s.io
        resources:
          - "*"
        verbs:
          - get
          - list
          - watch
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: view-custom-metrics
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: view-custom-metrics
      subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: User
          name: system:anonymous

    3. Create them in your cluster using one of the follow commands, depending on the metrics you're using.

       # kubectl create -f <RESOURCE_METRICS_MANIFEST>
       # kubectl create -f <CUSTOM_METRICS_MANIFEST>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html index d80dfc594b7..fd2c414222d 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html @@ -5,7 +5,7 @@ Managing HPAs with kubectl | Rancher Manager - + @@ -22,7 +22,7 @@ I0724 10:18:45.699620 1 api.go:93] Response Body: {"status":&quo I0724 10:18:45.699939 1 wrap.go:42] GET /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/%2A/fs_read?labelSelector=app%3Dhello-world: (12.431262ms) 200 [[kube-controller-manager/v1.10.1 (linux/amd64) kubernetes/d4ab475/system:serviceaccount:kube-system:horizontal-pod-autoscaler] 10.42.0.0:24268] I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} ...

    1. Check that the metrics API is accessible from kubectl.

    • If you are accessing the cluster directly, enter your Server URL in the kubectl config in the following format: https://<Kubernetes_URL>:6443.

      # kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    • If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: https://<RANCHER_URL>/k8s/clusters/<CLUSTER_ID>. Add the suffix /k8s/clusters/<CLUSTER_ID> to API path.

      # kubectl get --raw /k8s/clusters/<CLUSTER_ID>/apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html index 6f99502e4de..61fa4dabeae 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html @@ -5,13 +5,13 @@ Managing HPAs with the Rancher UI | Rancher Manager - +
    Version: v2.0-v2.4

    Managing HPAs with the Rancher UI

    Available as of v2.3.0

    The Rancher UI supports creating, managing, and deleting HPAs. You can configure CPU or memory usage as the metric that the HPA uses to scale.

    If you want to create HPAs that scale based on other metrics than CPU and memory, refer to Configuring HPA to Scale Using Custom Metrics with Prometheus.

    Creating an HPA​

    1. From the Global view, open the project that you want to deploy a HPA to.

    2. Click Resources > HPA.

    3. Click Add HPA.

    4. Enter a Name for the HPA.

    5. Select a Namespace for the HPA.

    6. Select a Deployment as scale target for the HPA.

    7. Specify the Minimum Scale and Maximum Scale for the HPA.

    8. Configure the metrics for the HPA. You can choose memory or CPU usage as the metric that will cause the HPA to scale the service up or down. In the Quantity field, enter the percentage of the workload's memory or CPU usage that will cause the HPA to scale the service. To configure other HPA metrics, including metrics available from Prometheus, you need to manage HPAs using kubectl.

    9. Click Create to create the HPA.

    Result: The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view.

    Get HPA Metrics and Status​

    1. From the Global view, open the project with the HPAs you want to look at.

    2. Click Resources > HPA. The HPA tab shows the number of current replicas.

    3. For more detailed metrics and status of a specific HPA, click the name of the HPA. This leads to the HPA detail page.

    Deleting an HPA​

    1. From the Global view, open the project that you want to delete an HPA from.

    2. Click Resources > HPA.

    3. Find the HPA which you would like to delete.

    4. Click ⋮ > Delete.

    5. Click Delete to confirm.

    Result: The HPA is deleted from the current cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html index e12337e3695..21cd0d71e0e 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html @@ -5,14 +5,14 @@ Testing HPAs with kubectl | Rancher Manager - +
    Version: v2.0-v2.4

    Testing HPAs with kubectl

    This document describes how to check the status of your HPAs after scaling them up or down with your load testing tool. For information on how to check the status from the Rancher UI (at least version 2.3.x), refer to Managing HPAs with the Rancher UI.

    For HPA to work correctly, service deployments should have resources request definitions for containers. Follow this hello-world example to test if HPA is working correctly.

    1. Configure kubectl to connect to your Kubernetes cluster.

    2. Copy the hello-world deployment manifest below.

      Hello World Manifest
      apiVersion: apps/v1beta2
      kind: Deployment
      metadata:
        labels:
          app: hello-world
        name: hello-world
        namespace: default
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: hello-world
        strategy:
          rollingUpdate:
            maxSurge: 1
            maxUnavailable: 0
          type: RollingUpdate
        template:
          metadata:
            labels:
              app: hello-world
          spec:
            containers:
            - image: rancher/hello-world
              imagePullPolicy: Always
              name: hello-world
              resources:
                requests:
                  cpu: 500m
                  memory: 64Mi
              ports:
              - containerPort: 80
                protocol: TCP
            restartPolicy: Always
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: hello-world
        namespace: default
      spec:
        ports:
        - port: 80
          protocol: TCP
          targetPort: 80
        selector:
          app: hello-world

    3. Deploy it to your cluster.

      # kubectl create -f <HELLO_WORLD_MANIFEST>

    4. Copy one of the HPAs below based on the metric type you're using:

      Hello World HPA: Resource Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 1000Mi
      Hello World HPA: Custom Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 100Mi
        - type: Pods
          pods:
            metricName: cpu_system
            targetAverageValue: 20m

    5. View the HPA info and description. Confirm that metric data is shown.

      Resource Metrics
      1. Enter the following commands.
        # kubectl get hpa
        NAME          REFERENCE                TARGETS                     MINPODS   MAXPODS   REPLICAS   AGE
        hello-world   Deployment/hello-world   1253376 / 100Mi, 0% / 50%   1         10        1          6m
        # kubectl describe hpa
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 20:21:16 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             1253376 / 100Mi
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>
      Custom Metrics
      1. Enter the following command.
        # kubectl describe hpa
        You should receive the output that follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Tue, 24 Jul 2018 18:36:28 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             3514368 / 100Mi
          "cpu_system" on pods:                                0 / 20m
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>

    6. Generate a load for the service to test that your pods autoscale as intended. You can use any load-testing tool (Hey, Gatling, etc.), but we're using Hey.

    7. Test that pod autoscaling works as intended.

      To Test Autoscaling Using Resource Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to two pods based on CPU Usage.

      1. View your HPA.
        # kubectl describe hpa
        You should receive output similar to what follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             10928128 / 100Mi
          resource cpu on pods  (as a percentage of request):  56% (280m) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:
          Type    Reason             Age   From                       Message
          ----    ------             ----  ----                       -------
          Normal  SuccessfulRescale  13s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm you've scaled to two pods.
           # kubectl get pods
        You should receive output similar to what follows:
           NAME                                                     READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-k8ph2                             1/1       Running   0          1m
           hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Upscale to 3 pods: CPU Usage Up to Target

      Use your load testing tool to upscale to 3 pods based on CPU usage with horizontal-pod-autoscaler-upscale-delay set to 3 minutes.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             9424896 / 100Mi
             resource cpu on pods  (as a percentage of request):  66% (333m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  4m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
         NAME                                                     READY     STATUS    RESTARTS   AGE
         hello-world-54764dfbf8-f46kh                             0/1       Running   0          1m
         hello-world-54764dfbf8-k8ph2                             1/1       Running   0          5m
         hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing to scale down to 1 pod when all metrics are below target for horizontal-pod-autoscaler-downscale-delay (5 minutes by default).

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             10070016 / 100Mi
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  6m    horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  1s    horizontal-pod-autoscaler  New size: 1; reason: All metrics below target

      To Test Autoscaling Using Custom Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale two pods based on CPU usage.

      1. Enter the following command.
          # kubectl describe hpa
        You should receive output similar to what follows.
          Name:                                                  hello-world
          Namespace:                                             default
          Labels:                                                <none>
          Annotations:                                           <none>
          CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
          Reference:                                             Deployment/hello-world
          Metrics:                                               ( current / target )
            resource memory on pods:                             8159232 / 100Mi
            "cpu_system" on pods:                                7m / 20m
            resource cpu on pods  (as a percentage of request):  64% (321m) / 50%
          Min replicas:                                          1
          Max replicas:                                          10
          Conditions:
            Type            Status  Reason              Message
            ----            ------  ------              -------
            AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
            ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
            ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
          Events:
            Type    Reason             Age   From                       Message
            ----    ------             ----  ----                       -------
            Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm two pods are running.
          # kubectl get pods
        You should receive output similar to what follows.
              NAME                           READY     STATUS    RESTARTS   AGE
              hello-world-54764dfbf8-5pfdr   1/1       Running   0          3s
              hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 3 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to three pods when the cpu_system usage limit is up to target.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows:
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             8374272 / 100Mi
             "cpu_system" on pods:                                27m / 20m
             resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  3s    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows:
           # kubectl get pods
           NAME                           READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-5pfdr   1/1       Running   0          3m
           hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
           hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 4 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale to four pods based on CPU usage. horizontal-pod-autoscaler-upscale-delay is set to three minutes by default.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8374272 / 100Mi
              "cpu_system" on pods:                                27m / 20m
              resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  4s    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm four pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
          NAME                           READY     STATUS    RESTARTS   AGE
          hello-world-54764dfbf8-2p9xb   1/1       Running   0          5m
          hello-world-54764dfbf8-5pfdr   1/1       Running   0          2m
          hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
          hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing tool to scale down to one pod when all metrics below target for horizontal-pod-autoscaler-downscale-delay.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive similar output to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8101888 / 100Mi
              "cpu_system" on pods:                                8m / 20m
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  8m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
              Normal   SuccessfulRescale             13s               horizontal-pod-autoscaler  New size: 1; reason: All metrics below target
      2. Enter the following command to confirm a single pods is running.
            # kubectl get pods
        You should receive output similar to what follows.
            NAME                           READY     STATUS    RESTARTS   AGE
            hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html index e56ffeeedcf..30c1f5f74a9 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html @@ -5,13 +5,13 @@ Kubernetes Registry and Docker Registry | Rancher Manager - +
    Version: v2.0-v2.4

    Kubernetes Registry and Docker Registry

    Registries are Kubernetes secrets containing credentials used to authenticate with private Docker registries.

    The word "registry" can mean two things, depending on whether it is used to refer to a Docker or Kubernetes registry:

    • A Docker registry contains Docker images that you can pull in order to use them in your deployment. The registry is a stateless, scalable server side application that stores and lets you distribute Docker images.
    • The Kubernetes registry is an image pull secret that your deployment uses to authenticate with a Docker registry.

    Deployments use the Kubernetes registry secret to authenticate with a private Docker registry and then pull a Docker image hosted on it.

    Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl.

    Creating a Registry

    Prerequisites: You must have a private registry available to use.

    1. From the Global view, select the project containing the namespace(s) where you want to add a registry.

    2. From the main menu, click Resources > Secrets > Registry Credentials. (For Rancher before v2.3, click Resources > Registries.)

    3. Click Add Registry.

    4. Enter a Name for the registry.

      Note: Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace.

    5. Select a Scope for the registry. You can either make the registry available for the entire project or a single namespace.

    6. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password.

    7. Click Save.

    Result:

    • Your secret is added to the project or namespace, depending on the scope you chose.
    • You can view the secret in the Rancher UI from the Resources > Registries view.
    • Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope.

    Using a Private Registry

    You can deploy a workload with an image from a private registry through the Rancher UI, or with kubectl.

    Using the Private Registry with the Rancher UI​

    To deploy a workload with an image from your private registry,

    1. Go to the project view,
    2. Click Resources > Workloads. In versions before v2.3.0, go to the Workloads tab.
    3. Click Deploy.
    4. Enter a unique name for the workload and choose a namespace.
    5. In the Docker Image field, enter the URL of the path to the Docker image in your private registry. For example, if your private registry is on Quay.io, you could use quay.io/<Quay profile name>/<Image name>.
    6. Click Launch.

    Result: Your deployment should launch, authenticate using the private registry credentials you added in the Rancher UI, and pull the Docker image that you specified.

    Using the Private Registry with kubectl​

    When you create the workload using kubectl, you need to configure the pod so that its YAML has the path to the image in the private registry. You also have to create and reference the registry secret because the pod only automatically gets access to the private registry credentials if it is created in the Rancher UI.

    The secret has to be created in the same namespace where the workload gets deployed.

    Below is an example pod.yml for a workload that uses an image from a private registry. In this example, the pod uses an image from Quay.io, and the .yml specifies the path to the image. The pod authenticates with the registry using credentials stored in a Kubernetes secret called testquay, which is specified in spec.imagePullSecrets in the name field:

    apiVersion: v1
    kind: Pod
    metadata:
      name: private-reg
    spec:
      containers:
      - name: private-reg-container
        image: quay.io/<Quay profile name>/<image name>
      imagePullSecrets:
      - name: testquay

    In this example, the secret named testquay is in the default namespace.

    You can use kubectl to create the secret with the private registry credentials. This command creates the secret named testquay:

    kubectl create secret docker-registry testquay \
        --docker-server=quay.io \
        --docker-username=<Profile name> \
        --docker-password=<password>

    To see how the secret is stored in Kubernetes, you can use this command:

    kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

    The result looks like this:

    {"auths":{"quay.io":{"username":"<Profile name>","password":"<password>","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}}

    After the workload is deployed, you can check if the image was pulled successfully:

    kubectl get events

    The result should look like this:

    14s         Normal    Scheduled          Pod    Successfully assigned default/private-reg2 to minikube
    11s         Normal    Pulling            Pod    pulling image "quay.io/<Profile name>/<image name>"
    10s         Normal    Pulled             Pod    Successfully pulled image "quay.io/<Profile name>/<image name>"

    For more information, refer to the Kubernetes documentation on creating a pod that uses your secret.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html index ce842fa9d07..3dba4af15b9 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html @@ -5,13 +5,13 @@ Adding Ingresses to Your Project | Rancher Manager - +
    Version: v2.0-v2.4

    Adding Ingresses to Your Project

    Ingress can be added for workloads to provide load balancing, SSL termination and host/path based routing. When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    1. From the Global view, open the project that you want to add ingress to.
    2. Click Resources in the main navigation bar. Click the Load Balancing tab. (In versions before v2.3.0, just click the Load Balancing tab.) Then click Add Ingress.
    3. Enter a Name for the ingress.
    4. Select an existing Namespace from the drop-down list. Alternatively, you can create a new namespace on the fly by clicking Add to a new namespace.
    5. Create ingress forwarding Rules. For help configuring the rules, refer to this section. If any of your ingress rules handle requests for encrypted ports, add a certificate to encrypt/decrypt communications.
    6. Optional: click Add Rule to create additional ingress rules. For example, after you create ingress rules to direct requests for your hostname, you'll likely want to create a default backend to handle 404s.

    Result: Your ingress is added to the project. The ingress begins enforcing your ingress rules.

    Ingress Rule Configuration

    Automatically generate a sslip.io hostname​

    If you choose this option, ingress routes requests to hostname to a DNS name that's automatically generated. Rancher uses sslip.io to automatically generates the DNS name. This option is best used for testing, not production environments.

    Note: To use this option, you must be able to resolve to sslip.io addresses.

    1. Add a Target Backend. By default, a workload is added to the ingress, but you can add more targets by clicking either Service or Workload.
    2. Optional: If you want specify a workload or service when a request is sent to a particular hostname path, add a Path for the target. For example, if you want requests for www.mysite.com/contact-us to be sent to a different service than www.mysite.com, enter /contact-us in the Path field. Typically, the first rule that you create does not include a path.
    3. Select a workload or service from the Target drop-down list for each target you've added.
    4. Enter the Port number that each target operates on.

    Specify a hostname to use​

    If you use this option, ingress routes requests for a hostname to the service or workload that you specify.

    1. Enter the hostname that your ingress will handle request forwarding for. For example, www.mysite.com.
    2. Add a Target Backend. By default, a workload is added to the ingress, but you can add more targets by clicking either Service or Workload.
    3. Optional: If you want specify a workload or service when a request is sent to a particular hostname path, add a Path for the target. For example, if you want requests for www.mysite.com/contact-us to be sent to a different service than www.mysite.com, enter /contact-us in the Path field. Typically, the first rule that you create does not include a path.
    4. Select a workload or service from the Target drop-down list for each target you've added.
    5. Enter the Port number that each target operates on.

    Use as the default backend​

    Use this option to set an ingress rule for handling requests that don't match any other ingress rules. For example, use this option to route requests that can't be found to a 404 page.

    Note: If you deployed Rancher using RKE, a default backend for 404s and 202s is already configured.

    1. Add a Target Backend. Click either Service or Workload to add the target.
    2. Select a service or workload from the Target drop-down list.

    Certificates​

    Note: You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see Adding SSL Certificates.

    1. Click Add Certificate.
    2. Select a Certificate from the drop-down list.
    3. Enter the Host using encrypted communication.
    4. To add additional hosts that use the certificate, click Add Hosts.

    Labels and Annotations​

    Add Labels and/or Annotations to provide metadata for your ingress.

    For a list of annotations available for use, see the Nginx Ingress Controller Documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html index 8b4997f30f1..a9d6ead28cf 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html @@ -5,13 +5,13 @@ Layer 4 and Layer 7 Load Balancing | Rancher Manager - +
    Version: v2.0-v2.4

    Layer 4 and Layer 7 Load Balancing

    Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing.

    Layer-4 Load Balancer​

    Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic.

    Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single globally managed config-map can be used to expose services on NGINX or third-party ingress.

    Note: It is possible to deploy a cluster with a non-cloud load balancer, such as MetalLB. However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE.

    Support for Layer-4 Load Balancing​

    Support for layer-4 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-4 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GCE cloud provider
    Azure AKSSupported by Azure cloud provider
    RKE on EC2Supported by AWS cloud provider
    RKE on DigitalOceanLimited NGINX or third-party Ingress*
    RKE on vSphereLimited NGINX or third party-Ingress*
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Limited NGINX or third-party Ingress*
    Third-party MetalLBLimited NGINX or third-party Ingress*

    * Services can be exposed through a single globally managed config-map.

    Layer-7 Load Balancer​

    Layer-7 load balancer (or the ingress controller) supports host and path-based load balancing and SSL termination. Layer-7 load balancer only forwards HTTP and HTTPS traffic and therefore they listen on ports 80 and 443 only. Cloud providers such as Amazon and Google support layer-7 load balancer. In addition, RKE clusters deploys the Nginx Ingress Controller.

    Support for Layer-7 Load Balancing​

    Support for layer-7 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-7 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GKE cloud provider
    Azure AKSNot Supported
    RKE on EC2Nginx Ingress Controller
    RKE on DigitalOceanNginx Ingress Controller
    RKE on vSphereNginx Ingress Controller
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Nginx Ingress Controller

    Host Names in Layer-7 Load Balancer​

    Some cloud-managed layer-7 load balancers (such as the ALB ingress controller on AWS) expose DNS addresses for ingress rules. You need to map (via CNAME) your domain name to the DNS address generated by the layer-7 load balancer.

    Other layer-7 load balancers, such as the Google Load Balancer or Nginx Ingress Controller, directly expose one or more IP addresses. Google Load Balancer provides a single routable IP address. Nginx Ingress Controller exposes the external IP of all nodes that run the Nginx Ingress Controller. You can do either of the following:

    1. Configure your own DNS to map (via A records) your domain name to the IP addresses exposes by the Layer-7 load balancer.
    2. Ask Rancher to generate an sslip.io host name for your ingress rule. Rancher will take one of your exposed IPs, say a.b.c.d, and generate a host name <ingressname>.<namespace>.a.b.c.d.sslip.io.

    The benefit of using sslip.io is that you obtain a working entrypoint URL immediately after you create the ingress rule. Setting up your own domain name, on the other hand, requires you to configure DNS servers and wait for DNS to propagate.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html index 51307ba6a41..f2d3abdce1e 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html @@ -5,13 +5,13 @@ Secrets | Rancher Manager - +
    Version: v2.0-v2.4

    Secrets

    Secrets store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs.

    This page is about secrets in general. For details on setting up a private registry, refer to the section on registries.

    When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    Creating Secrets

    When creating a secret, you can make it available for any deployment within a project, or you can limit it to a single namespace.

    1. From the Global view, select the project containing the namespace(s) where you want to add a secret.

    2. From the main menu, select Resources > Secrets. Click Add Secret.

    3. Enter a Name for the secret.

      Note: Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace.

    4. Select a Scope for the secret. You can either make the registry available for the entire project or a single namespace.

    5. From Secret Values, click Add Secret Value to add a key value pair. Add as many values as you need.

      Tip: You can add multiple key value pairs to the secret by copying and pasting.

    6. Click Save.

    Result: Your secret is added to the project or namespace, depending on the scope you chose. You can view the secret in the Rancher UI from the Resources > Secrets view.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    What's Next?

    Now that you have a secret added to the project or namespace, you can add it to a workload that you deploy.

    For more information on adding secret to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html index 0cc2ca31d3d..c8f7cc89cbb 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html @@ -5,13 +5,13 @@ Adding a Sidecar | Rancher Manager - +
    Version: v2.0-v2.4

    Adding a Sidecar

    A sidecar is a container that extends or enhances the main container in a pod. The main container and the sidecar share a pod, and therefore share the same network space and storage. You can add sidecars to existing workloads by using the Add a Sidecar option.

    1. From the Global view, open the project running the workload you want to add a sidecar to.

    2. Click Resources > Workloads. In versions before v2.3.0, select the Workloads tab.

    3. Find the workload that you want to extend. Select ⋮ icon (...) > Add a Sidecar.

    4. Enter a Name for the sidecar.

    5. Select a Sidecar Type. This option determines if the sidecar container is deployed before or after the main container is deployed.

      • Standard Container:

        The sidecar container is deployed after the main container.

      • Init Container:

        The sidecar container is deployed before the main container.

    6. From the Docker Image field, enter the name of the Docker image that you want to deploy in support of the main container. During deployment, Rancher pulls this image from Docker Hub. Enter the name exactly as it appears on Docker Hub.

    7. Set the remaining options. You can read about them in Deploying Workloads.

    8. Click Launch.

    Result: The sidecar is deployed according to your parameters. Following its deployment, you can view the sidecar by selecting ⋮ icon (...) > Edit for the main deployment.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html index 6a110d059be..ffc3ba90fc0 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Version: v2.0-v2.4

    Deploying Workloads

    Deploy a workload to run an application in one or more containers.

    1. From the Global view, open the project that you want to deploy a workload to.

      1. Click Resources > Workloads. (In versions before v2.3.0, click the Workloads tab.) From the Workloads view, click Deploy.

    3. Enter a Name for the workload.

    4. Select a workload type. The workload defaults to a scalable deployment, but you can change the workload type by clicking More options.

    5. From the Docker Image field, enter the name of the Docker image that you want to deploy to the project, optionally prefacing it with the registry host (e.g. quay.io, registry.gitlab.com, etc.). During deployment, Rancher pulls this image from the specified public or private registry. If no registry host is provided, Rancher will pull the image from Docker Hub. Enter the name exactly as it appears in the registry server, including any required path, and optionally including the desired tag (e.g. registry.gitlab.com/user/path/image:tag). If no tag is provided, the latest tag will be automatically used.

    6. Either select an existing namespace, or click Add to a new namespace and enter a new namespace.

    7. Click Add Port to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see Services.

    8. Configure the remaining options:

      • Environment Variables

        Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or ConfigMap.

      • Node Scheduling

      • Health Check

      • Volumes

        Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a ConfigMap.

        When you are deploying a Stateful Set, you should use a Volume Claim Template when using Persistent Volumes. This will ensure that Persistent Volumes are created dynamically when you scale your Stateful Set. This option is available in the UI as of Rancher v2.2.0.

      • Scaling/Upgrade Policy

        Amazon Note for Volumes:

        To mount an Amazon EBS volume:

    1. Click Show Advanced Options and configure:

      • Command
      • Networking
      • Labels & Annotations
      • Security and Host Config

    2. Click Launch.

    Result: The workload is deployed to the chosen namespace. You can view the workload's status from the project's Workloads view.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html index 946af234594..5bd3c05124f 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html @@ -5,13 +5,13 @@ Rolling Back Workloads | Rancher Manager - +
    Version: v2.0-v2.4

    Rolling Back Workloads

    Sometimes there is a need to rollback to the previous version of the application, either for debugging purposes or because an upgrade did not go as planned.

    1. From the Global view, open the project running the workload you want to rollback.

    2. Find the workload that you want to rollback and select Vertical ⋮ (... ) > Rollback.

    3. Choose the revision that you want to roll back to. Click Rollback.

    Result: Your workload reverts to the previous version that you chose. Wait a few minutes for the action to complete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html index 24d93dbf327..8d1ca92362a 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html @@ -5,13 +5,13 @@ Upgrading Workloads | Rancher Manager - +
    Version: v2.0-v2.4

    Upgrading Workloads

    When a new version of an application image is released on Docker Hub, you can upgrade any workloads running a previous version of the application to the new one.

    1. From the Global view, open the project running the workload you want to upgrade.

    2. Find the workload that you want to upgrade and select Vertical ⋮ (... ) > Edit.

    3. Update the Docker Image to the updated version of the application image on Docker Hub.

    4. Update any other options that you want to change.

    5. Review and edit the workload's Scaling/Upgrade policy.

      These options control how the upgrade rolls out to containers that are currently running. For example, for scalable deployments, you can choose whether you want to stop old pods before deploying new ones, or vice versa, as well as the upgrade batch size.

    6. Click Upgrade.

    Result: The workload begins upgrading its containers, per your specifications. Note that scaling up the deployment or updating the upgrade/scaling policy won't result in the pods recreation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/discover-services.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/discover-services.html index 461f076e792..96e303572d4 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/discover-services.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/discover-services.html @@ -5,13 +5,13 @@ 6. Service Discovery | Rancher Manager - +
    Version: v2.0-v2.4

    6. Service Discovery

    Service discovery is one of the core functionalities of any container-based environment. Once you have packaged and launched your application, the next step is making it discoverable to other containers in your environment or the external world. This document will describe how to use the service discovery support provided by Rancher v2.x so that you can find them by name.

    This document will also show you how to link the workloads and services that you migrated into Rancher v2.x. When you parsed your services from v1.6 using migration-tools CLI, it output two files for each service: one deployment manifest and one service manifest. You'll have to link these two files together before the deployment works correctly in v2.x.

    Resolve the output.txt Link Directive

    Resolve Link Directive

    Service Discovery: Rancher v1.6 vs. v2.x​

    For Rancher v2.x, we've replaced the Rancher DNS microservice used in v1.6 with native Kubernetes DNS support, which provides equivalent service discovery for Kubernetes workloads and pods. Former Cattle users can replicate all the service discovery features from Rancher v1.6 in v2.x. There's no loss of functionality.

    Kubernetes schedules a DNS pod and service in the cluster, which is similar to the Rancher v1.6 DNS microservice. Kubernetes then configures its kubelets to route all DNS lookups to this DNS service, which is skyDNS, a flavor of the default Kube-DNS implementation.

    The following table displays each service discovery feature available in the two Rancher releases.

    Service Discovery FeatureRancher v1.6Rancher v2.xDescription
    service discovery within and across stack (i.e., clusters)✓✓All services in the stack are resolvable by <service_name> and by <service_name>.<stack_name> across stacks.
    container discovery✓✓All containers are resolvable globally by their name.
    service alias name creation✓✓Adding an alias name to services and linking to other services using aliases.
    discovery of external services✓✓Pointing to services deployed outside of Rancher using the external IP(s) or a domain name.

    Service Discovery Within and Across Namespaces​

    When you create a new workload in v2.x (not migrated, more on that below), Rancher automatically creates a service with an identical name, and then links the service and workload together. If you don't explicitly expose a port, the default port of 42 is used. This practice makes the workload discoverable within and across namespaces by its name.

    Container Discovery​

    Individual pods running in the Kubernetes cluster also get a DNS record assigned, which uses dot notation as well: <POD_IP_ADDRESS>.<NAMESPACE_NAME>.pod.cluster.local. For example, a pod with an IP of 10.42.2.7 in the namespace default with a DNS name of cluster.local would have an entry of 10-42-2-7.default.pod.cluster.local.

    Pods can also be resolved using the hostname and subdomain fields if set in the pod spec. Details about this resolution is covered in the Kubernetes docs.

    Linking Migrated Workloads and Services​

    When you migrate v1.6 services to v2.x, Rancher does not automatically create a Kubernetes service record for each migrated deployment. Instead, you'll have to link the deployment and service together manually, using any of the methods listed below.

    In the image below, the web-deployment.yml and web-service.yml files created after parsing our migration example services are linked together.

    Linked Workload and Kubernetes Service

    Linked Workload and Kubernetes Service

    Service Name Alias Creation​

    Just as you can create an alias for Rancher v1.6 services, you can do the same for Rancher v2.x workloads. Similarly, you can also create DNS records pointing to services running externally, using either their hostname or IP address. These DNS records are Kubernetes service objects.

    Using the v2.x UI, use the context menu to navigate to the Project view. Then click Resources > Workloads > Service Discovery. (In versions before v2.3.0, click the Workloads > Service Discovery tab.) All existing DNS records created for your workloads are listed under each namespace.

    Click Add Record to create new DNS records. Then view the various options supported to link to external services or to create aliases for another workload, DNS record, or set of pods.

    Add Service Discovery Record

    Add Service Discovery Record

    The following table indicates which alias options are implemented natively by Kubernetes and which options are implemented by Rancher leveraging Kubernetes.

    OptionKubernetes-implemented?Rancher-implemented?
    Pointing to an external hostname✓
    Pointing to a set of pods that match a selector✓
    Pointing to an external IP address✓
    Pointing to another workload✓
    Create alias for another DNS record✓

    Next: Load Balancing​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/expose-services.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/expose-services.html index c2ebddc2616..e9981c39b11 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/expose-services.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/expose-services.html @@ -5,13 +5,13 @@ 3. Expose Your Services | Rancher Manager - +
    Version: v2.0-v2.4

    3. Expose Your Services

    In testing environments, you usually need to route external traffic to your cluster containers by using an unadvertised IP and port number, providing users access to their apps. You can accomplish this goal using port mapping, which exposes a workload (i.e., service) publicly over a specific port, provided you know your node IP address(es). You can either map a port using HostPorts (which exposes a service on a specified port on a single node) or NodePorts (which exposes a service on all nodes on a single port).

    Use this document to correct workloads that list ports in output.txt. You can correct it by either setting a HostPort or a NodePort.

    Resolve ports for the web Workload

    Resolve Ports

    What's Different About Exposing Services in Rancher v2.x?​

    In Rancher v1.6, we used the term Port Mapping for exposing an IP address and port where your you and your users can access a service.

    In Rancher v2.x, the mechanisms and terms for service exposure have changed and expanded. You now have two port mapping options: HostPorts (which is most synonymous with v1.6 port mapping, allows you to expose your app at a single IP and port) and NodePorts (which allows you to map ports on all of your cluster nodes, not just one).

    Unfortunately, port mapping cannot be parsed by the migration-tools CLI. If the services you're migrating from v1.6 to v2.x have port mappings set, you'll have to either set a HostPort or NodePort as a replacement.

    HostPort​

    A HostPort is a port exposed to the public on a specific node running one or more pod. Traffic to the node and the exposed port (<HOST_IP>:<HOSTPORT>) are routed to the requested container's private port. Using a HostPort for a Kubernetes pod in Rancher v2.x is synonymous with creating a public port mapping for a container in Rancher v1.6.

    In the following diagram, a user is trying to access an instance of Nginx, which is running within a pod on port 80. However, the Nginx deployment is assigned a HostPort of 9890. The user can connect to this pod by browsing to its host IP address, followed by the HostPort in use (9890 in case).

    HostPort Diagram

    HostPort Pros​

    • Any port available on the host can be exposed.
    • Configuration is simple, and the HostPort is set directly in the Kubernetes pod specifications. Unlike NodePort, no other objects need to be created to expose your app.

    HostPort Cons​

    • Limits the scheduling options for your pod, as only hosts with vacancies for your chosen port can be used.
    • If the scale of your workload is larger than the number of nodes in your Kubernetes cluster, the deployment fails.
    • Any two workloads that specify the same HostPort cannot be deployed to the same node.
    • If the host where your pods are running becomes unavailable, Kubernetes reschedules the pods to different nodes. Thus, if the IP address for your workload changes, external clients of your application will lose access to the pod. The same thing happens when you restart your pods—Kubernetes reschedules them to a different node.

    Setting HostPort​

    You can set a HostPort for migrated workloads (i.e., services) using the Rancher v2.x UI. To add a HostPort, browse to the project containing your workloads, and edit each workload that you want to expose, as shown below. Map the port that your service container exposes to the HostPort exposed on your target node.

    For example, for the web-deployment.yml file parsed from v1.6 that we've been using as a sample, we would edit its Kubernetes manifest, set the publish the port that the container uses, and then declare a HostPort listening on the port of your choice (9890) as shown below. You can then access your workload by clicking the link created in the Rancher UI.

    Port Mapping: Setting HostPort

    NodePort​

    A NodePort is a port that's open to the public on each of your cluster nodes. When the NodePort receives a request for any of the cluster hosts' IP address for the set NodePort value, NodePort (which is a Kubernetes service) routes traffic to a specific pod, regardless of what node it's running on. NodePort provides a static endpoint where external requests can reliably reach your pods.

    NodePorts help you circumvent an IP address shortcoming. Although pods can be reached by their IP addresses, they are disposable by nature. Pods are routinely destroyed and recreated, getting a new IP address with each replication. Therefore, IP addresses are not a reliable way to access your pods. NodePorts help you around this issue by providing a static service where they can always be reached. Even if your pods change their IP addresses, external clients dependent on them can continue accessing them without disruption, all without any knowledge of the pod re-creation occurring on the back end.

    In the following diagram, a user is trying to connect to an instance of Nginx running in a Kubernetes cluster managed by Rancher. Although he knows what NodePort Nginx is operating on (30216 in this case), he does not know the IP address of the specific node that the pod is running on. However, with NodePort enabled, he can connect to the pod using the IP address for any node in the cluster. Kubeproxy will forward the request to the correct node and pod.

    NodePort Diagram

    NodePorts are available within your Kubernetes cluster on an internal IP. If you want to expose pods external to the cluster, use NodePorts in conjunction with an external load balancer. Traffic requests from outside your cluster for <NodeIP>:<NodePort> are directed to the workload. The <NodeIP> can be the IP address of any node in your Kubernetes cluster.

    NodePort Pros​

    • Creating a NodePort service provides a static public endpoint to your workload pods. There, even if the pods are destroyed, Kubernetes can deploy the workload anywhere in the cluster without altering the public endpoint.
    • The scale of the pods is not limited by the number of nodes in the cluster. NodePort allows decoupling of public access from the number and location of pods.

    NodePort Cons​

    • When a NodePort is used, that <NodeIP>:<NodePort> is reserved in your Kubernetes cluster on all nodes, even if the workload is never deployed to the other nodes.
    • You can only specify a port from a configurable range (by default, it is 30000-32767).
    • An extra Kubernetes object (a Kubernetes service of type NodePort) is needed to expose your workload. Thus, finding out how your application is exposed is not straightforward.

    Setting NodePort​

    You can set a NodePort for migrated workloads (i.e., services) using the Rancher v2.x UI. To add a NodePort, browse to the project containing your workloads, and edit each workload that you want to expose, as shown below. Map the port that your service container exposes to a NodePort, which you'll be able to access from each cluster node.

    For example, for the web-deployment.yml file parsed from v1.6 that we've been using as a sample, we would edit its Kubernetes manifest, set the publish the port that the container uses, and then declare a NodePort. You can then access your workload by clicking the link created in the Rancher UI.

    Note:

    • If you set a NodePort without giving it a value, Rancher chooses a port at random from the following range: 30000-32767.
    • If you manually set a NodePort, you must assign it a value within the 30000-32767 range.
    Port Mapping: Setting NodePort

    Next: Configure Health Checks​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/install-and-configure-rancher.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/install-and-configure-rancher.html index d19d9c69a90..f765877688c 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/install-and-configure-rancher.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/install-and-configure-rancher.html @@ -5,13 +5,13 @@ 1. Get Started | Rancher Manager - +
    Version: v2.0-v2.4

    1. Get Started

    Get started with your migration to Rancher v2.x by installing Rancher and configuring your new Rancher environment.

    A. Install Rancher v2.x​

    The first step in migrating from v1.6 to v2.x is to install the Rancher v2.x Server side-by-side with your v1.6 Server, as you'll need your old install during the migration process. Due to the architecture changes between v1.6 and v2.x, there is no direct path for upgrade. You'll have to install v2.x independently and then migrate your v1.6 services to v2.x.

    New for v2.x, all communication to Rancher Server is encrypted. The procedures below instruct you not only on installation of Rancher, but also creation and installation of these certificates.

    Before installing v2.x, provision one host or more to function as your Rancher Server(s). You can find the requirements for these hosts in Server Requirements.

    After provisioning your node(s), install Rancher:

    • Docker Install

      For development environments, Rancher can be installed on a single node using Docker. This installation procedure deploys a single Rancher container to your host.

    • Kubernetes Install

      For production environments where your user base requires constant access to your cluster, we recommend installing Rancher in a high availability Kubernetes installation. This installation procedure provisions a three-node cluster and installs Rancher on each node using a Helm chart.

      Important Difference: Although you could install Rancher v1.6 in a high-availability Kubernetes configuration using an external database and a Docker command on each node, Rancher v2.x in a Kubernetes install requires an existing Kubernetes cluster. Review Kubernetes Install for full requirements.

    B. Configure Authentication​

    After your Rancher v2.x Server is installed, we recommend configuring external authentication (like Active Directory or GitHub) so that users can log into Rancher using their single sign-on. For a full list of supported authentication providers and instructions on how to configure them, see Authentication.

    Rancher v2.x Authentication

    Rancher v2.x Authentication

    Local Users​

    Although we recommend using an external authentication provider, Rancher v1.6 and v2.x both offer support for users local to Rancher. However, these users cannot be migrated from Rancher v1.6 to v2.x. If you used local users in Rancher v1.6 and want to continue this practice in v2.x, you'll need to manually recreate these user accounts and assign them access rights.

    As a best practice, you should use a hybrid of external and local authentication. This practice provides access to Rancher should your external authentication experience an interruption, as you can still log in using a local user account. Set up a few local accounts as administrative users of Rancher.

    SAML Authentication Providers​

    In Rancher v1.6, we encouraged our SAML users to use Shibboleth, as it was the only SAML authentication option we offered. However, to better support their minor differences, we've added more fully tested SAML providers for v2.x: Ping Identity, Microsoft ADFS, and FreeIPA.

    C. Provision a Cluster and Project​

    Begin work in Rancher v2.x by using it to provision a new Kubernetes cluster, which is similar to an environment in v1.6. This cluster will host your application deployments.

    A cluster and project in combined together in Rancher v2.x is equivalent to a v1.6 environment. A cluster is the compute boundary (i.e., your hosts) and a project is an administrative boundary (i.e., a grouping of namespaces used to assign access rights to users).

    There's more basic info on provisioning clusters in the headings below, but for full information, see Provisioning Kubernetes Clusters.

    Clusters​

    In Rancher v1.6, compute nodes were added to an environment. Rancher v2.x eschews the term environment for cluster, as Kubernetes uses this term for a team of computers instead of environment.

    Rancher v2.x lets you launch a Kubernetes cluster anywhere. Host your cluster using:

    Projects​

    Additionally, Rancher v2.x introduces projects, which are objects that divide clusters into different application groups that are useful for applying user permissions. This model of clusters and projects allow for multi-tenancy because hosts are owned by the cluster, and the cluster can be further divided into multiple projects where users can manage their apps, but not those of others.

    When you create a cluster, two projects are automatically created:

    • The System project, which includes system namespaces where important Kubernetes resources are running (like ingress controllers and cluster dns services)
    • The Default project.

    However, for production environments, we recommend creating your own project and giving it a descriptive name.

    After provisioning a new cluster and project, you can authorize your users to access and use project resources. Similarly to Rancher v1.6 environments, Rancher v2.x allows you to assign users to projects. By assigning users to projects, you can limit what applications and resources a user can access.

    D. Create Stacks​

    In Rancher v1.6, stacks were used to group together the services that belong to your application. In v2.x, you need to create namespaces, which are the v2.x equivalent of stacks, for the same purpose.

    In Rancher v2.x, namespaces are child objects to projects. When you create a project, a default namespace is added to the project, but you can create your own to parallel your stacks from v1.6.

    During migration, if you don't explicitly define which namespace a service should be deployed to, it's deployed to the default namespace.

    Just like v1.6, Rancher v2.x supports service discovery within and across namespaces (we'll get to service discovery soon).

    Next: Migrate Your Services​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/kubernetes-introduction.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/kubernetes-introduction.html index a22ea1d805e..5de0976e81d 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/kubernetes-introduction.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/kubernetes-introduction.html @@ -5,13 +5,13 @@ Kubernetes Introduction | Rancher Manager - +
    Version: v2.0-v2.4

    Kubernetes Introduction

    Rancher v2.x is built on the Kubernetes container orchestrator. This shift in underlying technology for v2.x is a large departure from v1.6, which supported several popular container orchestrators. Since Rancher is now based entirely on Kubernetes, it's helpful to learn the Kubernetes basics.

    The following table introduces and defines some key Kubernetes concepts.

    ConceptDefinition
    ClusterA collection of machines that run containerized applications managed by Kubernetes.
    NamespaceA virtual cluster, multiple of which can be supported by a single physical cluster.
    NodeOne of the physical or virtual machines that make up a cluster.
    PodThe smallest and simplest Kubernetes object. A pod represents a set of running containers on your cluster.
    DeploymentAn API object that manages a replicated application.
    WorkloadWorkloads are objects that set deployment rules for pods.

    Migration Cheatsheet​

    Because Rancher v1.6 defaulted to our Cattle container orchestrator, it primarily used terminology related to Cattle. However, because Rancher v2.x uses Kubernetes, it aligns with the Kubernetes naming standard. This shift could be confusing for people unfamiliar with Kubernetes, so we've created a table that maps terms commonly used in Rancher v1.6 to their equivalents in Rancher v2.x.

    Rancher v1.6Rancher v2.x
    ContainerPod
    ServicesWorkload
    Load BalancerIngress
    StackNamespace
    EnvironmentProject (Administration)/Cluster (Compute)
    HostNode
    CatalogHelm
    Port MappingHostPort (Single Node)/NodePort (All Nodes)

    More detailed information on Kubernetes concepts can be found in the [Kubernetes Concepts Documentation](https://kubernetes.io/docs/concepts/).

    Next: Get Started​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/load-balancing.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/load-balancing.html index a4c2161c7c1..a251ddae902 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/load-balancing.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/load-balancing.html @@ -5,13 +5,13 @@ 7. Load Balancing | Rancher Manager - +
    Version: v2.0-v2.4

    7. Load Balancing

    If your applications are public-facing and consume significant traffic, you should place a load balancer in front of your cluster so that users can always access their apps without service interruption. Typically, you can fulfill a high volume of service requests by horizontally scaling your deployment, which spins up additional application containers as traffic ramps up. However, this technique requires routing that distributes traffic across your nodes efficiently. In cases where you need to accommodate public traffic that scales up and down, you'll need a load balancer.

    As outlined in its documentation, Rancher v1.6 provided rich support for load balancing using its own microservice powered by HAProxy, which supports HTTP, HTTPS, TCP hostname, and path-based routing. Most of these same features are available in v2.x. However, load balancers that you used with v1.6 cannot be migrated to v2.x. You'll have to manually recreate your v1.6 load balancer in v2.x.

    If you encounter the output.txt text below after parsing your v1.6 Compose files to Kubernetes manifests, you'll have to resolve it by manually creating a load balancer in v2.x.

    output.txt Load Balancer Directive

    Resolve Load Balancer Directive

    Load Balancing Protocol Options​

    By default, Rancher v2.x replaces the v1.6 load balancer microservice with the native Kubernetes Ingress, which is backed by NGINX Ingress Controller for layer 7 load balancing. By default, Kubernetes Ingress only supports the HTTP and HTTPS protocols, not TCP. Load balancing is limited to these two protocols when using Ingress.

    TCP Required? See TCP Load Balancing Options

    Load Balancer Deployment​

    In Rancher v1.6, you could add port/service rules for configuring your HA proxy to load balance for target services. You could also configure the hostname/path-based routing rules.

    Rancher v2.x offers similar functionality, but load balancing is instead handled by Ingress. An Ingress is a specification of rules that a controller component applies to your load balancer. The actual load balancer can run outside of your cluster or within it.

    By default, Rancher v2.x deploys NGINX Ingress Controller on clusters provisioned using RKE (Rancher's own Kubernetes installer) to process the Kubernetes Ingress rules. The NGINX Ingress Controller is installed by default only in clusters provisioned by RKE. Clusters provisioned by cloud providers like GKE have their own Ingress Controllers that configure the load balancer. For this document, our scope is limited to the RKE-installed NGINX Ingress Controller only.

    RKE deploys NGINX Ingress Controller as a Kubernetes DaemonSet, meaning that an NGINX instance is deployed on every node in the cluster. NGINX acts like an Ingress Controller listening to Ingress creation within your entire cluster, and it also configures itself as the load balancer to satisfy the Ingress rules. The DaemonSet is configured with hostNetwork to expose two ports: 80 and 443.

    For more information NGINX Ingress Controller, their deployment as DaemonSets, deployment configuration options, see the RKE documentation.

    Load Balancing Architecture​

    Deployment of Ingress Controller in v2.x as a DaemonSet brings some architectural changes that v1.6 users should know about.

    In Rancher v1.6 you could deploy a scalable load balancer service within your stack. If you had four hosts in your Cattle environment, you could deploy one load balancer service with a scale of two and point to your application by appending port 80 to your two host IP Addresses. You could also launch another load balancer on the remaining two hosts to balance a different service again using port 80 because your load balancer is using different host IP Addresses).

    Rancher v1.6 Load Balancing Architecture

    Rancher v1.6 Load Balancing

    The Rancher v2.x Ingress Controller is a DaemonSet, it is globally deployed on all schedulable nodes to serve your entire Kubernetes Cluster. Therefore, when you program the Ingress rules, you must use a unique hostname and path to point to your workloads, as the load balancer node IP addresses and ports 80 and 443 are common access points for all workloads.

    Rancher v2.x Load Balancing Architecture

    Rancher v2.x Load Balancing

    Ingress Caveats​

    Although Rancher v2.x supports HTTP and HTTPS hostname and path-based load balancing, you must use unique host names and paths when configuring your workloads. This limitation derives from:

    • Ingress confinement to ports 80 and 443 (i.e, the ports HTTP[S] uses for routing).
    • The load balancer and the Ingress Controller is launched globally for the cluster as a DaemonSet.

    TCP Required? Rancher v2.x still supports TCP. See TCP Load Balancing Options for workarounds.

    Deploying Ingress​

    You can launch a new load balancer to replace your load balancer from v1.6. Using the Rancher v2.x UI, browse to the applicable project and choose Resources > Workloads > Load Balancing. (In versions before v2.3.0, click Workloads > Load Balancing.) Then click Deploy. During deployment, you can choose a target project or namespace.

    Prerequisite: Before deploying Ingress, you must have a workload deployed that's running a scale of two or more pods.

    Workload Scale

    For balancing between these two pods, you must create a Kubernetes Ingress rule. To create this rule, navigate to your cluster and project, and click Resources > Workloads > Load Balancing. (In versions before v2.3.0, click Workloads > Load Balancing.) Then click Add Ingress. This GIF below depicts how to add Ingress to one of your projects.

    Browsing to Load Balancer Tab and Adding Ingress

    Adding Ingress

    Similar to a service/port rules in Rancher v1.6, here you can specify rules targeting your workload's container port. The sections below demonstrate how to create Ingress rules.

    Configuring Host- and Path-Based Routing​

    Using Rancher v2.x, you can add Ingress rules that are based on host names or a URL path. Based on the rules you create, your NGINX Ingress Controller routes traffic to multiple target workloads or Kubernetes services.

    For example, let's say you have multiple workloads deployed to a single namespace. You can add an Ingress to route traffic to these two workloads using the same hostname but different paths, as depicted in the image below. URL requests to foo.com/name.html will direct users to the web workload, and URL requests to foo.com/login will direct users to the chat workload.

    Ingress: Path-Based Routing Configuration

    Ingress: Path-Based Routing Configuration

    Rancher v2.x also places a convenient link to the workloads on the Ingress record. If you configure an external DNS to program the DNS records, this hostname can be mapped to the Kubernetes Ingress address.

    Workload Links

    Load Balancer Links to Workloads

    The Ingress address is the IP address in your cluster that the Ingress Controller allocates for your workload. You can reach your workload by browsing to this IP address. Use kubectl command below to see the Ingress address assigned by the controller:

    kubectl get ingress

    HTTPS/Certificates Option​

    Rancher v2.x Ingress functionality supports the HTTPS protocol, but if you want to use it, you need to use a valid SSL/TLS certificate. While configuring Ingress rules, use the SSL/TLS Certificates section to configure a certificate.

    • We recommend uploading a certificate from a known certificate authority (you'll have to do this before configuring Ingress). Then, while configuring your load balancer, use the Choose a certificate option and select the uploaded certificate that you want to use.
    • If you have configured NGINX default certificate, you can select Use default ingress controller certificate.
    Load Balancer Configuration: SSL/TLS Certificate Section

    SSL/TLS Certificates Section

    TCP Load Balancing Options​

    Layer-4 Load Balancer​

    For the TCP protocol, Rancher v2.x supports configuring a Layer 4 load balancer using the cloud provider in which your Kubernetes cluster is deployed. Once this load balancer appliance is configured for your cluster, when you choose the option of a Layer-4 Load Balancer for port-mapping during workload deployment, Rancher automatically creates a corresponding load balancer service. This service will call the corresponding cloud provider and configure the load balancer appliance to route requests to the appropriate pods. See Cloud Providers for information on how to configure LoadBalancer services for your cloud provider.

    For example, if we create a deployment named myapp and specify a Layer 4 load balancer in the Port Mapping section, Rancher will automatically add an entry to the Load Balancer tab named myapp-loadbalancer.

    Workload Deployment: Layer 4 Load Balancer Creation

    Deploy Layer-4 Load Balancer

    Once configuration of the load balancer succeeds, the Rancher UI provides a link to your workload's public endpoint.

    NGINX Ingress Controller TCP Support by ConfigMaps​

    Although NGINX supports TCP, Kubernetes Ingress itself does not support the TCP protocol. Therefore, out-of-the-box configuration of NGINX Ingress Controller for TCP balancing isn't possible.

    However, there is a workaround to use NGINX's TCP balancing by creating a Kubernetes ConfigMap, as described in the Ingress GitHub readme. You can create a ConfigMap object that stores pod configuration parameters as key-value pairs, separate from the pod image, as described in the Kubernetes documentation.

    To configure NGINX to expose your services via TCP, you can add the ConfigMap tcp-services that should exist in the ingress-nginx namespace. This namespace also contains the NGINX Ingress Controller pods.

    Layer-4 Load Balancer: ConfigMap Workaround

    The key in the ConfigMap entry should be the TCP port that you want to expose for public access: <namespace/service name>:<service port>. As shown above, two workloads are listed in the Default namespace. For example, the first entry in the ConfigMap above instructs NGINX to expose the myapp workload (the one in the default namespace that's listening on private port 80) over external port 6790. Adding these entries to the ConfigMap automatically updates the NGINX pods to configure these workloads for TCP balancing. The workloads exposed should be available at <NodeIP>:<TCP Port>. If they are not accessible, you might have to expose the TCP port explicitly using a NodePort service.

    Rancher v2.x Load Balancing Limitations​

    Cattle provided feature-rich load balancer support that is well documented. Some of these features do not have equivalents in Rancher v2.x. This is the list of such features:

    • No support for SNI in current NGINX Ingress Controller.
    • TCP load balancing requires a load balancer appliance enabled by cloud provider within the cluster. There is no Ingress support for TCP on Kubernetes.
    • Only ports 80 and 443 can be configured for HTTP/HTTPS routing via Ingress. Also Ingress Controller is deployed globally as a DaemonSet and not launched as a scalable service. Also, users cannot assign random external ports to be used for balancing. Therefore, users need to ensure that they configure unique hostname/path combinations to avoid routing conflicts using the same two ports.
    • There is no way to specify port rule priority and ordering.
    • Rancher v1.6 added support for draining backend connections and specifying a drain timeout. This is not supported in Rancher v2.x.
    • There is no support for specifying a custom stickiness policy and a custom load balancer config to be appended to the default config as of now in Rancher v2.x. There is some support, however, available in native Kubernetes for customizing the NGINX configuration as noted in the NGINX Ingress Controller Custom Configuration Documentation.

    Finished!​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/migrate-services.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/migrate-services.html index 7cd434b373a..20ae89b167f 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/migrate-services.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/migrate-services.html @@ -5,13 +5,13 @@ 2. Migrate Your Services | Rancher Manager - +
    Version: v2.0-v2.4

    2. Migrate Your Services

    Although your services from v1.6 won't work in Rancher v2.x by default, that doesn't mean you have to start again from square one, manually rebuilding your applications in v2.x. To help with migration from v1.6 to v2.x, Rancher has developed a migration tool. The migration-tools CLI is a utility that helps you recreate your applications in Rancher v2.x. This tool exports your Rancher v1.6 services as Compose files and converts them to a Kubernetes manifest that Rancher v2.x can consume.

    Additionally, for each Rancher v1.6-specific Compose directive that cannot be consumed by Kubernetes, migration-tools CLI provides instructions on how to manually recreate them in Rancher v2.x.

    This command line interface tool will:

    • Export Compose files (i.e., docker-compose.yml and rancher-compose.yml) for each stack in your v1.6 Cattle environment. For every stack, files are exported to a unique folder: <EXPORT_DIR>/<ENV_NAME>/<STACK_NAME>.

    • Parse Compose files that you’ve exported from your Rancher v1.6 stacks and converts them to Kubernetes manifests that Rancher v2.x can consume. The tool also outputs a list of directives present in the Compose files that cannot be converted automatically to Rancher v2.x. These are directives that you’ll have to manually configure using the Rancher v2.x UI.

    A. Download the migration-tools CLI​

    The migration-tools CLI for your platform can be downloaded from our GitHub releases page. The tools are available for Linux, Mac, and Windows platforms.

    B. Configure the migration-tools CLI​

    After you download migration-tools CLI, rename it and make it executable.

    1. Open a terminal window and change to the directory that contains the migration-tool file.

    2. Rename the file to migration-tools so that it no longer includes the platform name.

    3. Enter the following command to make migration-tools executable:

      chmod +x migration-tools

    C. Run the migration-tools CLI​

    Next, use the migration-tools CLI to export all stacks in all of the Cattle environments into Compose files. Then, for stacks that you want to migrate to Rancher v2.x, convert the Compose files into Kubernetes manifest.

    Prerequisite: Create an Account API Key to authenticate with Rancher v1.6 when using the migration-tools CLI.

    1. Export the Docker Compose files for your Cattle environments and stacks from Rancher v1.6.

      In the terminal window, execute the following command, replacing each placeholder with your values.

      migration-tools export --url http://<RANCHER_URL:PORT> --access-key <RANCHER_ACCESS_KEY> --secret-key <RANCHER_SECRET_KEY> --export-dir <EXPORT_DIR> --all

      Step Result: migration-tools exports Compose files (docker-compose.yml and rancher-compose.yml) for each stack in the --export-dir directory. If you omitted this option, Compose files are output to your current directory.

      A unique directory is created for each environment and stack. For example, if we export each environment/stack from Rancher v1.6, the following directory structure is created:

      export/                            # migration-tools --export-dir
      |--<ENVIRONMENT>/                  # Rancher v1.6 ENVIRONMENT
          |--<STACK>/                    # Rancher v1.6 STACK
               |--docker-compose.yml     # STANDARD DOCKER DIRECTIVES FOR ALL STACK SERVICES
               |--rancher-compose.yml    # RANCHER-SPECIFIC DIRECTIVES FOR ALL STACK SERVICES
               |--README.md              # README OF CHANGES FROM v1.6 to v2.x

    1. Convert the exported Compose files to Kubernetes manifest.

      Execute the following command, replacing each placeholder with the absolute path to your Stack's Compose files. If you want to migrate multiple stacks, you'll have to re-run the command for each pair of Compose files that you exported.

      migration-tools parse --docker-file <DOCKER_COMPOSE_ABSOLUTE_PATH> --rancher-file <RANCHER_COMPOSE_ABSOLUTE_PATH>

      Note: If you omit the --docker-file and --rancher-file options from your command, migration-tools uses the current working directory to find Compose files.

    Want full usage and options for the migration-tools CLI? See the Migration Tools CLI Reference.

    migration-tools CLI Output​

    After you run the migration-tools parse command, the following files are output to your target directory.

    OutputDescription
    output.txtThis file lists how to recreate your Rancher v1.6-specific functionality in Kubernetes. Each listing links to the relevant blog articles on how to implement it in Rancher v2.x.
    Kubernetes manifest specsMigration-tools internally invokes Kompose to generate a Kubernetes manifest for each service you're migrating to v2.x. Each YAML spec file is named for the service you're migrating.

    Why are There Separate Deployment and Service Manifests?​

    To make an application publicly accessible by URL, a Kubernetes service is required in support of the deployment. A Kubernetes service is a REST object that abstracts access to the pods in the workload. In other words, a service provides a static endpoint to the pods by mapping a URL to pod(s) Therefore, even if the pods change IP address, the public endpoint remains unchanged. A service object points to its corresponding deployment (workload) by using selector labels.

    When a you export a service from Rancher v1.6 that exposes public ports, migration-tools CLI parses those ports to a Kubernetes service spec that links to a deployment YAML spec.

    Migration Example File Output​

    If we parse the two example files from Migration Example Files, docker-compose.yml and rancher-compose.yml, the following files are output:

    FileDescription
    web-deployment.yamlA file containing Kubernetes container specs for a Let's Chat deployment.
    web-service.yamlA file containing specs for the Let's Chat service.
    database-deployment.yamlA file containing container specs for the MongoDB deployment in support of Let's Chat.
    webLB-deployment.yamlA file containing container specs for an HAProxy deployment that's serving as a load balancer.1
    webLB-service.yamlA file containing specs for the HAProxy service.1
    1 Because Rancher v2.x uses Ingress for load balancing, we won't be migrating our Rancher v1.6 load balancer to v2.x.

    D. Re-Deploy Services as Kubernetes Manifests​

    Note: Although these instructions deploy your v1.6 services in Rancher v2.x, they will not work correctly until you adjust their Kubernetes manifests.

    You can deploy the Kubernetes manifests created by migration-tools by importing them into Rancher v2.x.

    Receiving an ImportYaml Error?

    Delete the YAML directive listed in the error message. These are YAML directives from your v1.6 services that Kubernetes can't read.

    Deploy Services: Import Kubernetes Manifest

    Deploy Services

    Following importation, you can view your v1.6 services in the v2.x UI as Kubernetes manifests by using the context menu to select <CLUSTER> > <PROJECT> that contains your services. The imported manifests will display on the Resources > Workloads and on the tab at Resources > Workloads > Service Discovery. (In Rancher v2.x before v2.3.0, these are on the Workloads and Service Discovery tabs in the top navigation bar.)

    Imported Services

    Imported Services

    What Now?​

    Although the migration-tool CLI parses your Rancher v1.6 Compose files to Kubernetes manifests, there are discrepancies between v1.6 and v2.x that you must address by manually editing your parsed Kubernetes manifests. In other words, you need to edit each workload and service imported into Rancher v2.x, as displayed below.

    Edit Migrated Services

    Edit Migrated Workload

    As mentioned in Migration Tools CLI Output, the output.txt files generated during parsing lists the manual steps you must make for each deployment. Review the upcoming topics for more information on manually editing your Kubernetes specs.

    Open your output.txt file and take a look at its contents. When you parsed your Compose files into Kubernetes manifests, migration-tools CLI output a manifest for each workload that it creates for Kubernetes. For example, our when our Migration Example Files are parsed into Kubernetes manifests, output.txt lists each resultant parsed Kubernetes manifest file (i.e., workloads). Each workload features a list of action items to restore operations for the workload in v2.x.

    Output.txt Example

    output.txt

    The following table lists possible directives that may appear in output.txt, what they mean, and links on how to resolve them.

    DirectiveInstructions
    portsRancher v1.6 Port Mappings cannot be migrated to v2.x. Instead, you must manually declare either a HostPort or NodePort, which are similar to Port Mappings.
    health_checkThe Rancher v1.6 health check microservice has been replaced with native Kubernetes health checks, called probes. Recreate your v1.6 health checks in v2.0 using probes.
    labelsRancher v1.6 uses labels to implement a variety of features in v1.6. In v2.x, Kubernetes uses different mechanisms to implement these features. Click through on the links here for instructions on how to address each label.

    io.rancher.container.pull_image: In v1.6, this label instructed deployed containers to pull a new version of the image upon restart. In v2.x, this functionality is replaced by the imagePullPolicy directive.

    io.rancher.scheduler.global: In v1.6, this label scheduled a container replica on every cluster host. In v2.x, this functionality is replaced by Daemon Sets.

    io.rancher.scheduler.affinity: In v2.x, affinity is applied in a different way.
    linksDuring migration, you must create links between your Kubernetes workloads and services for them to function properly in v2.x.
    scaleIn v1.6, scale refers to the number of container replicas running on a single node. In v2.x, this feature is replaced by replica sets.
    start_on_createNo Kubernetes equivalent. No action is required from you.

    Next: Expose Your Services​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/monitor-apps.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/monitor-apps.html index b072b4c338a..3d75b05952e 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/monitor-apps.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/monitor-apps.html @@ -5,13 +5,13 @@ 4. Configure Health Checks | Rancher Manager - +
    Version: v2.0-v2.4

    4. Configure Health Checks

    Rancher v1.6 provided TCP and HTTP health checks on your nodes and services using its own health check microservice. These health checks monitored your containers to confirm they're operating as intended. If a container failed a health check, Rancher would destroy the unhealthy container and then replicates a healthy one to replace it.

    For Rancher v2.x, we've replaced the health check microservice, leveraging instead Kubernetes' native health check support.

    Use this document to correct Rancher v2.x workloads and services that list health_check in output.txt. You can correct them by configuring a liveness probe (i.e., a health check).

    For example, for the image below, we would configure liveness probes for the web and weblb workloads (i.e., the Kubernetes manifests output by migration-tools CLI).

    Resolve health_check for the web and webLB Workloads

    Resolve health_check

    Rancher v1.6 Health Checks​

    In Rancher v1.6, you could add health checks to monitor a particular service's operations. These checks were performed by the Rancher health check microservice, which is launched in a container on a node separate from the node hosting the monitored service (however, Rancher v1.6.20 and later also runs a local health check container as a redundancy for the primary health check container on another node). Health check settings were stored in the rancher-compose.yml file for your stack.

    The health check microservice features two types of health checks, which have a variety of options for timeout, check interval, etc.:

    • TCP health checks:

      These health checks check if a TCP connection opens at the specified port for the monitored service. For full details, see the Rancher v1.6 documentation.

    • HTTP health checks:

      These health checks monitor HTTP requests to a specified path and check whether the response is expected response (which is configured along with the health check).

    The following diagram displays the health check microservice evaluating a container running Nginx. Notice that the microservice is making its check across nodes.

    Rancher v1.6 Health Checks

    Rancher v2.x Health Checks​

    In Rancher v2.x, the health check microservice is replaced with Kubernetes's native health check mechanisms, called probes. These probes, similar to the Rancher v1.6 health check microservice, monitor the health of pods over TCP and HTTP.

    However, probes in Rancher v2.x have some important differences, which are described below. For full details about probes, see the Kubernetes documentation.

    Local Health Checks​

    Unlike the Rancher v1.6 health checks performed across hosts, probes in Rancher v2.x occur on same host, performed by the kubelet.

    Multiple Probe Types​

    Kubernetes includes two different types of probes: liveness checks and readiness checks.

    • Liveness Check:

      Checks if the monitored container is running. If the probe reports failure, Kubernetes kills the pod, and then restarts it according to the deployment restart policy.

    • Readiness Check:

      Checks if the container is ready to accept and serve requests. If the probe reports failure, the pod is sequestered from the public until it self heals.

    The following diagram displays kubelets running probes on containers they are monitoring (kubelets are the primary "agent" running on each node). The node on the left is running a liveness probe, while the one of the right is running a readiness check. Notice that the kubelet is scanning containers on its host node rather than across nodes, as in Rancher v1.6.

    Rancher v2.x Probes

    Configuring Probes in Rancher v2.x​

    The migration-tool CLI cannot parse health checks from Compose files to Kubernetes manifest. Therefore, if want you to add health checks to your Rancher v2.x workloads, you'll have to add them manually.

    Using the Rancher v2.x UI, you can add TCP or HTTP health checks to Kubernetes workloads. By default, Rancher asks you to configure a readiness check for your workloads and applies a liveness check using the same configuration. Optionally, you can define a separate liveness check.

    If the probe fails, the container is restarted per the restartPolicy defined in the workload specs. This setting is equivalent to the strategy parameter for health checks in Rancher v1.6.

    Configure probes by using the Health Check section while editing deployments called out in output.txt.

    Edit Deployment: Health Check Section

    Health Check Section

    Configuring Checks​

    While you create a workload using Rancher v2.x, we recommend configuring a check that monitors the health of the deployment's pods.

    TCP checks monitor your deployment's health by attempting to open a connection to the pod over a specified port. If the probe can open the port, it's considered healthy. Failure to open it is considered unhealthy, which notifies Kubernetes that it should kill the pod and then replace it according to its restart policy. (this applies to Liveness probes, for Readiness probes, it will mark the pod as Unready).

    You can configure the probe along with values for specifying its behavior by selecting the TCP connection opens successfully option in the Health Check section. For more information, see Deploying Workloads. For help setting probe timeout and threshold values, see Health Check Parameter Mappings.

    TCP Check

    When you configure a readiness check using Rancher v2.x, the readinessProbe directive and the values you've set are added to the deployment's Kubernetes manifest. Configuring a readiness check also automatically adds a liveness check (livenessProbe) to the deployment.

    Configuring Separate Liveness Checks​

    While configuring a readiness check for either the TCP or HTTP protocol, you can configure a separate liveness check by clicking the Define a separate liveness check. For help setting probe timeout and threshold values, see Health Check Parameter Mappings.

    Separate Liveness Check

    Additional Probing Options​

    Rancher v2.x, like v1.6, lets you perform health checks using the TCP and HTTP protocols. However, Rancher v2.x also lets you check the health of a pod by running a command inside of it. If the container exits with a code of 0 after running the command, the pod is considered healthy.

    You can configure a liveness or readiness check that executes a command that you specify by selecting the Command run inside the container exits with status 0 option from Health Checks while deploying a workload.

    Healthcheck Execute Command

    Health Check Parameter Mappings​

    While configuring readiness checks and liveness checks, Rancher prompts you to fill in various timeout and threshold values that determine whether the probe is a success or failure. The reference table below shows you the equivalent health check values from Rancher v1.6.

    Rancher v1.6 Compose ParameterRancher v2.x Kubernetes Parameter
    porttcpSocket.port
    response_timeouttimeoutSeconds
    healthy_thresholdfailureThreshold
    unhealthy_thresholdsuccessThreshold
    intervalperiodSeconds
    initializing_timeoutinitialDelaySeconds
    strategyrestartPolicy

    Next: Schedule Your Services​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/schedule-services.html b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/schedule-services.html index 0d4a5636679..1c58aa85959 100644 --- a/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/schedule-services.html +++ b/v2.0-v2.4/how-to-guides/new-user-guides/migrate-from-v1.6-v2.x/schedule-services.html @@ -5,14 +5,14 @@ 5. Schedule Your Services | Rancher Manager - +
    Version: v2.0-v2.4

    5. Schedule Your Services

    In v1.6, objects called services were used to schedule containers to your cluster hosts. Services included the Docker image for an application, along with configuration settings for a desired state.

    In Rancher v2.x, the equivalent object is known as a workload. Rancher v2.x retains all scheduling functionality from v1.6, but because of the change from Cattle to Kubernetes as the default container orchestrator, the terminology and mechanisms for scheduling workloads has changed.

    Workload deployment is one of the more important and complex aspects of container orchestration. Deploying pods to available shared cluster resources helps maximize performance under optimum compute resource use.

    You can schedule your migrated v1.6 services while editing a deployment. Schedule services by using Workload Type and Node Scheduling sections, which are shown below.

    Editing Workloads: Workload Type and Node Scheduling Sections

    Workload Type and Node Scheduling Sections

    What's Different for Scheduling Services?​

    Rancher v2.x retains all methods available in v1.6 for scheduling your services. However, because the default container orchestration system has changed from Cattle to Kubernetes, the terminology and implementation for each scheduling option has changed.

    In v1.6, you would schedule a service to a host while adding a service to a Stack. In Rancher v2.x., the equivalent action is to schedule a workload for deployment. The following composite image shows a comparison of the UI used for scheduling in Rancher v2.x versus v1.6.

    Node Scheduling: Rancher v2.x vs v1.6

    Node Scheduling Options​

    Rancher offers a variety of options when scheduling nodes to host workload pods (i.e., scheduling hosts for containers in Rancher v1.6).

    You can choose a scheduling option as you deploy a workload. The term workload is synonymous with adding a service to a Stack in Rancher v1.6). You can deploy a workload by using the context menu to browse to a cluster project (<CLUSTER> > <PROJECT> > Workloads).

    The sections that follow provide information on using each scheduling options, as well as any notable changes from Rancher v1.6. For full instructions on deploying a workload in Rancher v2.x beyond just scheduling options, see Deploying Workloads.

    Optionv1.6 Featurev2.x Feature
    Schedule a certain number of pods?✓✓
    Schedule pods to specific node?✓✓
    Schedule to nodes using labels?✓✓
    Schedule to nodes using label affinity/anti-affinity rules?✓✓
    Schedule based on resource constraints?✓✓
    Preventing scheduling specific services to specific hosts?✓✓
    Schedule services globally?✓✓

    Schedule a certain number of pods​

    In v1.6, you could control the number of container replicas deployed for a service. You can schedule pods the same way in v2.x, but you'll have to set the scale manually while editing a workload.

    Resolve Scale

    During migration, you can resolve scale entries in output.txt by setting a value for the Workload Type option Scalable deployment depicted below.

    Scalable Deployment Option

    Workload Scale

    Scheduling Pods to a Specific Node​

    Just as you could schedule containers to a single host in Rancher v1.6, you can schedule pods to single node in Rancher v2.x

    As you deploy a workload, use the Node Scheduling section to choose a node to run your pods on. The workload below is being scheduled to deploy an Nginx image with a scale of two pods on a specific node.

    Rancher v2.x: Workload Deployment

    Workload Tab and Group by Node Icon

    Rancher schedules pods to the node you select if 1) there are compute resource available for the node and 2) you've configured port mapping to use the HostPort option, that there are no port conflicts.

    If you expose the workload using a NodePort that conflicts with another workload, the deployment gets created successfully, but no NodePort service is created. Therefore, the workload isn't exposed outside of the cluster.

    After the workload is created, you can confirm that the pods are scheduled to your chosen node. From the project view, click Resources > Workloads. (In versions before v2.3.0, click the Workloads tab.) Click the Group by Node icon to sort your workloads by node. Note that both Nginx pods are scheduled to the same node.

    Pods Scheduled to Same Node

    Scheduling Using Labels​

    In Rancher v2.x, you can constrain pods for scheduling to specific nodes (referred to as hosts in v1.6). Using labels, which are key/value pairs that you can attach to different Kubernetes objects, you can configure your workload so that pods you've labeled are assigned to specific nodes (or nodes with specific labels are automatically assigned workload pods).

    Label Scheduling Options
    Label ObjectRancher v1.6Rancher v2.x
    Schedule by Node?✓✓
    Schedule by Pod?✓✓

    Applying Labels to Nodes and Pods​

    Before you can schedule pods based on labels, you must first apply labels to your pods or nodes.

    Hooray! All the labels that you manually applied in Rancher v1.6 (but not the ones automatically created by Rancher) are parsed by migration-tools CLI, meaning you don't have to manually reapply labels.

    To apply labels to pods, make additions to the Labels and Annotations section as you configure your workload. After you complete workload configuration, you can view the label by viewing each pod that you've scheduled. To apply labels to nodes, edit your node and make additions to the Labels section.

    Label Affinity/AntiAffinity​

    Some of the most-used scheduling features in v1.6 were affinity and anti-affinity rules.

    output.txt Affinity Label

    Affinity Label

    • Affinity

      Any pods that share the same label are scheduled to the same node. Affinity can be configured in one of two ways:

      AffinityDescription
      HardA hard affinity rule means that the host chosen must satisfy all the scheduling rules. If no such host can be found, the workload will fail to deploy. In the Kubernetes manifest, this rule translates to the nodeAffinity directive.

      To use hard affinity, configure a rule using the Require ALL of section (see figure below).
      SoftRancher v1.6 user are likely familiar with soft affinity rules, which try to schedule the deployment per the rule, but can deploy even if the rule is not satisfied by any host.

      To use soft affinity, configure a rule using the Prefer Any of section (see figure below).

    Affinity Rules: Hard and Soft
    ![Affinity Rules](/img/node-scheduling-affinity.png)

    • AntiAffinity

      Any pods that share the same label are scheduled to different nodes. In other words, while affinity attracts a specific label to each other, anti-affinity repels a label from itself, so that pods are scheduled to different nodes.

      You can create an anti-affinity rules using either hard or soft affinity. However, when creating your rule, you must use either the is not set or not in list operator.

      For anti-affinity rules, we recommend using labels with phrases like NotIn and DoesNotExist, as these terms are more intuitive when users are applying anti-affinity rules.

      AntiAffinity Operators

      AntiAffinity

    Detailed documentation for affinity/anti-affinity is available in the Kubernetes Documentation.

    Affinity rules that you create in the UI update your workload, adding pod affinity/anti-affinity directives to the workload Kubernetes manifest specs.

    Preventing Scheduling Specific Services to Specific Nodes​

    In Rancher v1.6 setups, you could prevent services from being scheduled to specific nodes with the use of labels. In Rancher v2.x, you can reproduce this behavior using native Kubernetes scheduling options.

    In Rancher v2.x, you can prevent pods from being scheduled to specific nodes by applying taints to a node. Pods will not be scheduled to a tainted node unless it has special permission, called a toleration. A toleration is a special label that allows a pod to be deployed to a tainted node. While editing a workload, you can apply tolerations using the Node Scheduling section. Click Show advanced options.

    Applying Tolerations

    Tolerations

    For more information, see the Kubernetes documentation on taints and tolerations.

    Scheduling Global Services​

    Rancher v1.6 included the ability to deploy global services, which are services that deploy duplicate containers to each host in the environment (i.e., nodes in your cluster using Rancher v2.x terms). If a service has the io.rancher.scheduler.global: 'true' label declared, then Rancher v1.6 schedules a service container on each host in the environment.

    output.txt Global Service Label

    Global Service Label

    In Rancher v2.x, you can schedule a pod to each node using a Kubernetes DaemonSet, which is a specific type of workload ). A DaemonSet functions exactly like a Rancher v1.6 global service. The Kubernetes scheduler deploys a pod on each node of the cluster, and as new nodes are added, the scheduler will start new pods on them provided they match the scheduling requirements of the workload. Additionally, in v2.x, you can also limit a DaemonSet to be deployed to nodes that have a specific label.

    To create a daemonset while configuring a workload, choose Run one pod on each node from the Workload Type options.

    Workload Configuration: Choose run one pod on each node to configure daemonset

    choose Run one pod on each node

    Scheduling Pods Using Resource Constraints​

    While creating a service in the Rancher v1.6 UI, you could schedule its containers to hosts based on hardware requirements that you choose. The containers are then scheduled to hosts based on which ones have bandwidth, memory, and CPU capacity.

    In Rancher v2.x, you can still specify the resources required by your pods. However, these options are unavailable in the UI. Instead, you must edit your workload's manifest file to declare these resource constraints.

    To declare resource constraints, edit your migrated workloads, editing the Security & Host sections.

    • To reserve a minimum hardware reservation available for your pod(s), edit the following sections:

      • Memory Reservation
      • CPU Reservation
      • NVIDIA GPU Reservation

    • To set a maximum hardware limit for your pods, edit:

      • Memory Limit
      • CPU Limit
    Scheduling: Resource Constraint Settings

    Resource Constraint Settings

    You can find more detail about these specs and how to use them in the Kubernetes Documentation.

    Next: Service Discovery​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/installation/resources/chart-options.html b/v2.0-v2.4/installation/resources/chart-options.html index 594790fb5d9..1ff9ee63c0c 100644 --- a/v2.0-v2.4/installation/resources/chart-options.html +++ b/v2.0-v2.4/installation/resources/chart-options.html @@ -5,13 +5,13 @@ Rancher Helm Chart Options | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher Helm Chart Options

    The Rancher Helm chart options reference moved to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/about-authentication.html b/v2.0-v2.4/pages-for-subheaders/about-authentication.html index 10ce1a5187e..d22128aae64 100644 --- a/v2.0-v2.4/pages-for-subheaders/about-authentication.html +++ b/v2.0-v2.4/pages-for-subheaders/about-authentication.html @@ -5,13 +5,13 @@ Authentication | Rancher Manager - +
    Version: v2.0-v2.4

    Authentication

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters.

    This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.

    External vs. Local Authentication​

    The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted.

    Auth ServiceAvailable as of
    Microsoft Active Directoryv2.0.0
    GitHubv2.0.0
    Microsoft Azure ADv2.0.3
    FreeIPAv2.0.5
    OpenLDAPv2.0.5
    Microsoft AD FSv2.0.7
    PingIdentityv2.0.7
    Keycloakv2.1.0
    Oktav2.2.0
    Google OAuthv2.3.0
    Shibbolethv2.4.0

    However, Rancher also provides [local authentication](/v2.0-v2.4/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users).

    In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if your external authentication provider is unavailable or undergoing maintenance.

    Users and Groups​

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see Role Based Access Control.

    Note: Local authentication does not support creating or managing groups.

    For more information, see Users and Groups

    Scope of Rancher Authorization​

    After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available:

    Access LevelDescription
    Allow any valid UsersAny user in the authorization service can access Rancher. We generally discourage use of this setting!
    Allow members of Clusters, Projects, plus Authorized Users and OrganizationsAny user in the authorization service and any group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any user in the authentication service or group you add to the Authorized Users and Organizations list may log in to Rancher.
    Restrict access to only Authorized Users and OrganizationsOnly users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher.

    To set the Rancher access level for users in the authorization service, follow these steps:

    1. From the Global view, click Security > Authentication.

    2. Use the Site Access options to configure the scope of user authorization. The table above explains the access level for each option.

    3. Optional: If you choose an option other than Allow any valid Users, you can add users to the list of authorized users and organizations by searching for them in the text field that appears.

    4. Click Save.

    Result: The Rancher access configuration settings are applied.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    External Authentication Configuration and Principal Users​

    Configuration of external authentication requires:

    • A local user assigned the administrator role, called hereafter the local principal.
    • An external user that can authenticate with your external authentication service, called hereafter the external principal.

    Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects.

    1. Sign into Rancher as the local principal and complete configuration of external authentication.

      Sign In

    2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.

      Principal ID Sharing

    3. After you complete configuration, Rancher automatically signs out the local principal.

      Sign Out Local Principal

    4. Then, Rancher automatically signs you back in as the external principal.

      Sign In External Principal

    5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.

      Sign In External Principal

    6. The external principal and the local principal share the same access rights.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/about-provisioning-drivers.html b/v2.0-v2.4/pages-for-subheaders/about-provisioning-drivers.html index 0aaa39fd240..2a347127fa2 100644 --- a/v2.0-v2.4/pages-for-subheaders/about-provisioning-drivers.html +++ b/v2.0-v2.4/pages-for-subheaders/about-provisioning-drivers.html @@ -5,13 +5,13 @@ Provisioning Drivers | Rancher Manager - +
    Version: v2.0-v2.4

    Provisioning Drivers

    Drivers in Rancher allow you to manage which providers can be used to deploy hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    Rancher Drivers​

    With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it.

    There are two types of drivers within Rancher:

    Cluster Drivers​

    Available as of v2.2.0

    Cluster drivers are used to provision hosted Kubernetes clusters, such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.

    By default, Rancher has activated several hosted Kubernetes cloud providers including:

    There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:

    Node Drivers​

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/about-rke1-templates.html b/v2.0-v2.4/pages-for-subheaders/about-rke1-templates.html index 116bcd0276c..568983e3ceb 100644 --- a/v2.0-v2.4/pages-for-subheaders/about-rke1-templates.html +++ b/v2.0-v2.4/pages-for-subheaders/about-rke1-templates.html @@ -5,13 +5,13 @@ RKE Templates | Rancher Manager - +
    Version: v2.0-v2.4

    RKE Templates

    Available as of Rancher v2.3.0

    RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters.

    RKE is the Rancher Kubernetes Engine, which is the tool that Rancher uses to provision Kubernetes clusters.

    With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users.

    RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced.

    Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users.

    If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template.

    As of Rancher v2.3.3, you can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters.

    The core features of RKE templates allow DevOps and security teams to:

    • Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices
    • Prevent less technical users from making uninformed choices when provisioning clusters
    • Share different templates with different sets of users and groups
    • Delegate ownership of templates to users who are trusted to make changes to them
    • Control which users can create templates
    • Require users to create clusters from a template

    Configurable Settings​

    RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider:

    • Cloud provider options
    • Pod security options
    • Network providers
    • Ingress controllers
    • Network security configuration
    • Network plugins
    • Private registry URL and credentials
    • Add-ons
    • Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services

    The add-on section of an RKE template is especially powerful because it allows a wide range of customization options.

    Scope of RKE Templates​

    RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider.

    RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to RKE Templates and Hardware.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    As of v2.3.3, the settings of an existing cluster can be saved as an RKE template. This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the template is updated, and the cluster is upgraded to use a newer version of the template. The new template can also be used to create new clusters.

    Example Scenarios​

    When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users.

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    Some of the example scenarios include the following:

    Template Management​

    When you create an RKE template, it is available in the Rancher UI from the Global view under Tools > RKE Templates. When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public.

    Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings.

    RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision.

    In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the Allow User Override toggle over each setting in the Rancher UI when the template is created.

    For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option.

    The documents in this section explain the details of RKE template management:

    An example YAML configuration file for a template is provided for reference.

    Applying Templates​

    You can create a cluster from a template that you created, or from a template that has been shared with you.

    If the RKE template owner creates a new revision of the template, you can upgrade your cluster to that revision.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    As of Rancher v2.3.3, you can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    Standardizing Hardware​

    RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, you use RKE templates in conjunction with other tools.

    YAML Customization​

    If you define an RKE template as a YAML file, you can modify this example RKE template YAML. The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the rancher_kubernetes_engine_config directive in the YAML.

    The RKE documentation also has annotated cluster.yml files that you can use for reference.

    For guidance on available options, refer to the RKE documentation on cluster configuration.

    Add-ons​

    The add-on section of the RKE template configuration file works the same way as the add-on section of a cluster configuration file.

    The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster.

    Some things you could do with add-ons include:

    • Install applications on the Kubernetes cluster after it starts
    • Install plugins on nodes that are deployed with a Kubernetes daemonset
    • Automatically set up namespaces, service accounts, or role binding

    The RKE template configuration must be nested within the rancher_kubernetes_engine_config directive. To set add-ons, when creating the template, you will click Edit as YAML. Then use the addons directive to add a manifest, or the addons_include directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the user-defined add-ons documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/about-the-api.html b/v2.0-v2.4/pages-for-subheaders/about-the-api.html index 0cba85ad338..446d817d37e 100644 --- a/v2.0-v2.4/pages-for-subheaders/about-the-api.html +++ b/v2.0-v2.4/pages-for-subheaders/about-the-api.html @@ -5,13 +5,13 @@ API | Rancher Manager - +
    Version: v2.0-v2.4

    API

    How to use the API​

    The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it, click on your user avatar in the upper right corner. Under API & Keys, you can find the URL endpoint as well as create API keys.

    Authentication​

    API requests must include authentication information. Authentication is done with HTTP basic authentication using API Keys. API keys can create new clusters and have access to multiple clusters via /v3/clusters/. Cluster and project roles apply to these keys and restrict what clusters and projects the account can see and what actions they can take.

    By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. For details on how to invalidate them, refer to the API tokens page.

    Making requests​

    The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, see here.

    • Every type has a Schema which describes:
      • The URL to get to the collection of this type of resources
      • Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
      • Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
      • Every field that filtering is allowed on
      • What HTTP verb methods are available for the collection itself, or for individual resources in the collection.

    • So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a X-Api-Schemas header. From there you can follow the collection link on each schema to know where to list resources, and other links inside of the returned resources to get any other information.

    • In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (/v3/<type>) or get a specific resource (/v3/<type>/<id>). Anything deeper than that is subject to change in future releases.

    • Resources have relationships between each other called links. Each resource includes a map of links with the name of the link and the URL to retrieve that information. Again you should GET the resource and then follow the URL in the links map, not construct these strings yourself.

    • Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP POST to the URL in the actions map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.

    • To edit a resource, send a HTTP PUT to the links.update link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.

    • To delete a resource, send a HTTP DELETE to the links.remove link on the resource. If the link is missing then you don't have permission to update the resource.

    • To create a new resource, HTTP POST to the collection URL in the schema (which is /v3/<type>).

    Filtering​

    Most collections can be filtered on the server-side by common fields using HTTP query parameters. The filters map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just field=value. Modifiers can be added to the field name, e.g. field_gt=42 for "field is greater than 42". See the API spec for full details.

    Sorting​

    Most collections can be sorted on the server-side by common fields using HTTP query parameters. The sortLinks map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.

    Pagination​

    API responses are paginated with a limit of 100 resources per page by default. This can be changed with the limit query parameter, up to a maximum of 1000, e.g. /v3/pods?limit=1000. The pagination map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/access-clusters.html b/v2.0-v2.4/pages-for-subheaders/access-clusters.html index 5c89d07084c..f131d8b0cf5 100644 --- a/v2.0-v2.4/pages-for-subheaders/access-clusters.html +++ b/v2.0-v2.4/pages-for-subheaders/access-clusters.html @@ -5,13 +5,13 @@ Cluster Access | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Access

    This section is about what tools can be used to access clusters managed by Rancher.

    For information on how to give users permission to access a cluster, see the section on adding users to clusters.

    For more information on roles-based access control, see this section.

    For information on how to set up an authentication system, see this section.

    Rancher UI​

    Rancher provides an intuitive user interface for interacting with your clusters. All options available in the UI use the Rancher API. Therefore any action possible in the UI is also possible in the Rancher CLI or Rancher API.

    kubectl​

    You can use the Kubernetes command-line tool, kubectl, to manage your clusters. You have two options for using kubectl:

    • Rancher kubectl shell: Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part. For more information, see Accessing Clusters with kubectl Shell.
    • Terminal remote connection: You can also interact with your clusters by installing kubectl on your local desktop and then copying the cluster's kubeconfig file to your local ~/.kube/config directory. For more information, see Accessing Clusters with kubectl and a kubeconfig File.

    Rancher CLI​

    You can control your clusters by downloading Rancher's own command-line interface, Rancher CLI. This CLI tool can interact directly with different clusters and projects or pass them kubectl commands.

    Rancher API​

    Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an API key. To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on View in API for any Rancher UI object.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/advanced-options.html b/v2.0-v2.4/pages-for-subheaders/advanced-options.html index 46266056a91..b0f7880aa48 100644 --- a/v2.0-v2.4/pages-for-subheaders/advanced-options.html +++ b/v2.0-v2.4/pages-for-subheaders/advanced-options.html @@ -5,13 +5,13 @@ Advanced | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/advanced-user-guides.html b/v2.0-v2.4/pages-for-subheaders/advanced-user-guides.html index 7d3aea7db6b..4d192ab977a 100644 --- a/v2.0-v2.4/pages-for-subheaders/advanced-user-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/advanced-user-guides.html @@ -5,13 +5,13 @@ Advanced User Guides | Rancher Manager - +
    Version: v2.0-v2.4

    Advanced User Guides

    Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.

    It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/air-gap-helm2.html b/v2.0-v2.4/pages-for-subheaders/air-gap-helm2.html index dc3c507912a..68135d1f104 100644 --- a/v2.0-v2.4/pages-for-subheaders/air-gap-helm2.html +++ b/v2.0-v2.4/pages-for-subheaders/air-gap-helm2.html @@ -5,13 +5,13 @@ Installing Rancher in an Air Gapped Environment with Helm 2 | Rancher Manager - +
    Version: v2.0-v2.4

    Installing Rancher in an Air Gapped Environment with Helm 2

    After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.

    If you are using Helm 2, we recommend migrating to Helm 3 because it is simpler to use and more secure than Helm 2.

    This section provides a copy of the older instructions for installing Rancher on a Kubernetes cluster using Helm 2 in an air air gap environment, and it is intended to be used if upgrading to Helm 3 is not feasible.

    This section is about installations of Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Throughout the installations instructions, there will be tabs for either a high availability Kubernetes installation or a single-node Docker installation.

    Air Gapped Kubernetes Installations​

    This section covers how to install Rancher on a Kubernetes cluster in an air gapped environment.

    A Kubernetes installation is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

    Air Gapped Docker Installations​

    These instructions also cover how to install Rancher on a single node in an air gapped environment.

    The Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a docker run command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    Important: If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.

    Instead of running the Docker installation, you have the option to follow the Kubernetes Install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a Kubernetes Installation.

    Installation Outline

    Next: Prepare your Node(s)​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/air-gapped-helm-cli-install.html b/v2.0-v2.4/pages-for-subheaders/air-gapped-helm-cli-install.html index 6218dd8b022..578722c8ec6 100644 --- a/v2.0-v2.4/pages-for-subheaders/air-gapped-helm-cli-install.html +++ b/v2.0-v2.4/pages-for-subheaders/air-gapped-helm-cli-install.html @@ -5,13 +5,13 @@ Air Gapped Helm CLI Install | Rancher Manager - +
    Version: v2.0-v2.4

    Air Gapped Helm CLI Install

    This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.

    For more information on each installation option, refer to this page.

    Throughout the installation instructions, there will be tabs for each installation option.

    Important: If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.

    Installation Outline

    1. Set up infrastructure and private registry
    2. Collect and publish images to your private registry
    3. Set up a Kubernetes cluster (Skip this step for Docker installations)
    4. Install Rancher

    Upgrades

    To upgrade Rancher with Helm CLI in an air gap environment, follow this procedure.

    Next: Prepare your Node(s)​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/authentication-config.html b/v2.0-v2.4/pages-for-subheaders/authentication-config.html index 9296b535b6f..8a2191add65 100644 --- a/v2.0-v2.4/pages-for-subheaders/authentication-config.html +++ b/v2.0-v2.4/pages-for-subheaders/authentication-config.html @@ -5,13 +5,13 @@ Authentication Config | Rancher Manager - +
    Version: v2.0-v2.4

    Authentication Config

    In the following tutorials, you will learn how to manage users and groups, create local users, configure Google OAuth, configure Active Directory (AD), configure OpenLDAP, configure FreeIPA, configure Azure AD, configure GitHub, configure Keycloak, configure PingIdentity (SAML), configure Okta (SAML), configure Shibboleth (SAML), and how to configure Microsoft AD Federation Service (SAML).

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/authentication-permissions-and-global-configuration.html b/v2.0-v2.4/pages-for-subheaders/authentication-permissions-and-global-configuration.html index fdf89235484..9ad5c2cd3ae 100644 --- a/v2.0-v2.4/pages-for-subheaders/authentication-permissions-and-global-configuration.html +++ b/v2.0-v2.4/pages-for-subheaders/authentication-permissions-and-global-configuration.html @@ -5,13 +5,13 @@ Authentication, Permissions and Global Configuration | Rancher Manager - +
    Version: v2.0-v2.4

    Authentication, Permissions and Global Configuration

    After installation, the system administrator should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.

    First Log In​

    After you log into Rancher for the first time, Rancher will prompt you for a Rancher Server URL.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.

    Important! After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.

    Authentication​

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.

    For more information how authentication works and how to configure each provider, see Authentication.

    Authorization​

    Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.

    For more information how authorization works and how to customize roles, see Roles Based Access Control (RBAC).

    Pod Security Policies​

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.

    For more information how to create and use PSPs, see Pod Security Policies.

    Provisioning Drivers​

    Drivers in Rancher allow you to manage which providers can be used to provision hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    For more information, see Provisioning Drivers.

    Adding Kubernetes Versions into Rancher​

    Available as of v2.3.0

    With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. v1.15.X), but not intended to upgrade Kubernetes minor versions (i.e. v1.X.0) as Kubernetes tends to deprecate or add APIs between minor versions.

    The information that Rancher uses to provision RKE clusters is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see Rancher Kubernetes Metadata.

    Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision RKE clusters.

    For more information on how metadata works and how to configure metadata config, see Rancher Kubernetes Metadata.

    Enabling Experimental Features​

    Available as of v2.3.0

    Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about feature flags.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/backup-restore-and-disaster-recovery.html b/v2.0-v2.4/pages-for-subheaders/backup-restore-and-disaster-recovery.html index 8b6e8365d0e..7bb1653053e 100644 --- a/v2.0-v2.4/pages-for-subheaders/backup-restore-and-disaster-recovery.html +++ b/v2.0-v2.4/pages-for-subheaders/backup-restore-and-disaster-recovery.html @@ -5,13 +5,13 @@ Backups and Disaster Recovery | Rancher Manager - +
    Version: v2.0-v2.4

    Backups and Disaster Recovery

    This section is devoted to protecting your data in a disaster scenario.

    To protect yourself from a disaster scenario, you should create backups on a regular basis.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/best-practices.html b/v2.0-v2.4/pages-for-subheaders/best-practices.html index 95836ed9b5c..b4a80fc15a4 100644 --- a/v2.0-v2.4/pages-for-subheaders/best-practices.html +++ b/v2.0-v2.4/pages-for-subheaders/best-practices.html @@ -5,13 +5,13 @@ Best Practices Guide | Rancher Manager - +
    Version: v2.0-v2.4

    Best Practices Guide

    The purpose of this section is to consolidate best practices for Rancher implementations. This also includes recommendations for related technologies, such as Kubernetes, Docker, containers, and more. The objective is to improve the outcome of a Rancher implementation using the operational experience of Rancher and its customers.

    If you have any questions about how these might apply to your use case, please contact your Customer Success Manager or Support.

    Use the navigation bar on the left to find the current best practices for managing and deploying the Rancher Server.

    For more guidance on best practices, you can consult these resources:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/checklist-for-production-ready-clusters.html b/v2.0-v2.4/pages-for-subheaders/checklist-for-production-ready-clusters.html index 5c16839cc9c..7360b34ed9a 100644 --- a/v2.0-v2.4/pages-for-subheaders/checklist-for-production-ready-clusters.html +++ b/v2.0-v2.4/pages-for-subheaders/checklist-for-production-ready-clusters.html @@ -5,14 +5,14 @@ Checklist for Production-Ready Clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Checklist for Production-Ready Clusters

    In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services.

    For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on node requirements.

    This is a shortlist of best practices that we strongly recommend for all production clusters.

    For a full list of all the best practices that we recommend, refer to the best practices section.

    Node Requirements​

    • Make sure your nodes fulfill all of the node requirements, including the port requirements.

    Back up etcd​

    • Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure etcd Recurring Snapshots for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.

    Cluster Architecture​

    • Nodes should have one of the following role configurations:
      • etcd
      • controlplane
      • etcd and controlplane
      • worker (the worker role should not be used or added on nodes with the etcd or controlplane role)
    • Have at least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • Assign two or more nodes the controlplane role for master component high availability.
    • Assign two or more nodes the worker role for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    For more information about the number of nodes for each Kubernetes role, refer to the section on recommended architecture.

    Logging and Monitoring​

    • Configure alerts/notifiers for Kubernetes components (System Service).
    • Configure logging for cluster analysis and post-mortems.

    Reliability​

    • Perform load tests on your cluster to verify that its hardware can support your workloads.

    Networking​

    • Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for heartbeat-interval is 500, and the default setting for election-timeout is 5000. These settings for etcd tuning allow etcd to run in most networks (except really high latency networks).
    • Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using Kubernetes Cloud Provider resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cis-scan-guides.html b/v2.0-v2.4/pages-for-subheaders/cis-scan-guides.html index 3b0406facdf..4ec8d8e7628 100644 --- a/v2.0-v2.4/pages-for-subheaders/cis-scan-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/cis-scan-guides.html @@ -5,13 +5,13 @@ CIS Scan Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cis-scans.html b/v2.0-v2.4/pages-for-subheaders/cis-scans.html index 685d366cbf1..082f2dfb33c 100644 --- a/v2.0-v2.4/pages-for-subheaders/cis-scans.html +++ b/v2.0-v2.4/pages-for-subheaders/cis-scans.html @@ -5,13 +5,13 @@ CIS Scans | Rancher Manager - +
    Version: v2.0-v2.4

    CIS Scans

    Available as of v2.4.0

    Prerequisites

    To run security scans on a cluster and access the generated reports, you must be an Administrator or Cluster Owner.

    Rancher can only run security scans on clusters that were created with RKE, which includes custom clusters and clusters that Rancher created in an infrastructure provider such as Amazon EC2 or GCE. Imported clusters and clusters in hosted Kubernetes providers can't be scanned by Rancher.

    The security scan cannot run in a cluster that has Windows nodes.

    You will only be able to see the CIS scan reports for clusters that you have access to.

    How-to Guides

    Please refer here for how-to guides on CIS scans.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cli-with-rancher.html b/v2.0-v2.4/pages-for-subheaders/cli-with-rancher.html index b45d2c8bfe5..ba17c823374 100644 --- a/v2.0-v2.4/pages-for-subheaders/cli-with-rancher.html +++ b/v2.0-v2.4/pages-for-subheaders/cli-with-rancher.html @@ -5,13 +5,13 @@ CLI with Rancher | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cluster-alerts.html b/v2.0-v2.4/pages-for-subheaders/cluster-alerts.html index a605e793447..3063cf55524 100644 --- a/v2.0-v2.4/pages-for-subheaders/cluster-alerts.html +++ b/v2.0-v2.4/pages-for-subheaders/cluster-alerts.html @@ -5,13 +5,13 @@ Cluster Alerts | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Alerts

    To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. When an event occurs, your alert is triggered, and you are sent a notification. You can then, if necessary, follow up with corrective actions.

    About Alerts

    Notifiers and alerts are built on top of the Prometheus Alertmanager. Leveraging these tools, Rancher can notify cluster owners and project owners of events they need to address.

    Before you can receive alerts, you must configure one or more notifier in Rancher.

    When you create a cluster, some alert rules are predefined. You can receive these alerts if you configure a notifier for them.

    For details about what triggers the predefined alerts, refer to the documentation on default alerts.

    Alert Event Examples​

    Some examples of alert events are:

    • A Kubernetes master component entering an unhealthy state.
    • A node or workload error occurring.
    • A scheduled deployment taking place as planned.
    • A node's hardware resources becoming overstressed.

    Alerts Triggered by Prometheus Queries​

    When you edit an alert rule, you will have the opportunity to configure the alert to be triggered based on a Prometheus expression. For examples of expressions, refer to this page.

    Monitoring must be enabled before you can trigger alerts with custom Prometheus queries or expressions.

    Urgency Levels​

    You can set an urgency level for each alert. This urgency appears in the notification you receive, helping you to prioritize your response actions. For example, if you have an alert configured to inform you of a routine deployment, no action is required. These alerts can be assigned a low priority level. However, if a deployment fails, it can critically impact your organization, and you need to react quickly. Assign these alerts a high priority level.

    Scope of Alerts​

    The scope for alerts can be set at either the cluster level or project level.

    At the cluster level, Rancher monitors components in your Kubernetes cluster, and sends you alerts related to:

    • The state of your nodes.
    • The system services that manage your Kubernetes cluster.
    • The resource events from specific system services.
    • The Prometheus expression cross the thresholds

    Managing Cluster Alerts​

    After you set up cluster alerts, you can manage each alert object. To manage alerts, browse to the cluster containing the alerts, and then select Tools > Alerts that you want to manage. You can:

    • Deactivate/Reactive alerts
    • Edit alert settings
    • Delete unnecessary alerts
    • Mute firing alerts
    • Unmute muted alerts

    Adding Cluster Alerts

    As a cluster owner, you can configure Rancher to send you alerts for cluster events.

    Prerequisite: Before you can receive cluster alerts, you must add a notifier.

    1. From the Global view, navigate to the cluster that you want to configure cluster alerts for. Select Tools > Alerts. Then click Add Alert Group.

    2. Enter a Name for the alert that describes its purpose, you could group alert rules for the different purpose.

    3. Based on the type of alert you want to create, refer to the cluster alert configuration section.

    4. Continue adding more Alert Rule to the group.

    5. Finally, choose the notifiers to send the alerts to.

      • You can set up multiple notifiers.
      • You can change notifier recipients on the fly.

    6. Click Create.

    Result: Your alert is configured. A notification is sent when the alert is triggered.

    Cluster Alert Configuration

    System Service Alerts

    This alert type monitor for events that affect one of the Kubernetes master components, regardless of the node it occurs on.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Select the System Services option, and then select an option from the dropdown:

    Is​

    The alert will be triggered when the selected Kubernetes master component is unhealthy.

    Send a​

    Select the urgency level of the alert. The options are:

    • Critical: Most urgent

    • Warning: Normal urgency

    • Info: Least urgent

      Select the urgency level based on the importance of the service and how many nodes fill the role within your cluster. For example, if you're making an alert for the etcd service, select Critical. If you're making an alert for redundant schedulers, Warning is more appropriate.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.

    Resource Event Alerts

    This alert type monitors for specific events that are thrown from a resource type.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Choose the type of resource event that triggers an alert. The options are:

    • Normal: triggers an alert when any standard resource event occurs.
    • Warning: triggers an alert when unexpected resource events occur.

    Select a resource type from the Choose a Resource drop-down that you want to trigger an alert.

    Send a​

    Select the urgency level of the alert.

    • Critical: Most urgent
    • Warning: Normal urgency
    • Info: Least urgent

    Select the urgency level of the alert by considering factors such as how often the event occurs or its importance. For example:

    • If you set a normal alert for pods, you're likely to receive alerts often, and individual pods usually self-heal, so select an urgency of Info.
    • If you set a warning alert for StatefulSets, it's very likely to impact operations, so select an urgency of Critical.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.

    Node Alerts

    This alert type monitors for events that occur on a specific node.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Select the Node option, and then make a selection from the Choose a Node drop-down.

    Is​

    Choose an event to trigger the alert.

    • Not Ready: Sends you an alert when the node is unresponsive.
    • CPU usage over: Sends you an alert when the node raises above an entered percentage of its processing allocation.
    • Mem usage over: Sends you an alert when the node raises above an entered percentage of its memory allocation.

    Send a​

    Select the urgency level of the alert.

    • Critical: Most urgent
    • Warning: Normal urgency
    • Info: Least urgent

    Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of Info, but a node that is Not Ready deems an urgency of Critical.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.

    Node Selector Alerts

    This alert type monitors for events that occur on any node on marked with a label. For more information, see the Kubernetes documentation for Labels.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Select the Node Selector option, and then click Add Selector to enter a key value pair for a label. This label should be applied to one or more of your nodes. Add as many selectors as you'd like.

    Is​

    Choose an event to trigger the alert.

    • Not Ready: Sends you an alert when selected nodes are unresponsive.
    • CPU usage over: Sends you an alert when selected nodes raise above an entered percentage of processing allocation.
    • Mem usage over: Sends you an alert when selected nodes raise above an entered percentage of memory allocation.

    Send a​

    Select the urgency level of the alert.

    • Critical: Most urgent
    • Warning: Normal urgency
    • Info: Least urgent

    Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of Info, but a node that is Not Ready deems an urgency of Critical.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.

    CIS Scan Alerts

    Available as of v2.4.0

    This alert type is triggered based on the results of a CIS scan.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Select CIS Scan.

    Is​

    Choose an event to trigger the alert:

    • Completed Scan
    • Has Failure

    Send a​

    Select the urgency level of the alert.

    • Critical: Most urgent
    • Warning: Normal urgency
    • Info: Least urgent

    Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's CPU raises above 60% deems an urgency of Info, but a node that is Not Ready deems an urgency of Critical.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.

    Metric Expression Alerts

    This alert type monitors for the overload from Prometheus expression querying, it would be available after you enable monitoring.

    Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

    When a​

    Input or select an Expression, the dropdown shows the original metrics from Prometheus, including:

    Is​

    Choose a comparison:

    • Equal: Trigger alert when expression value equal to the threshold.
    • Not Equal: Trigger alert when expression value not equal to the threshold.
    • Greater Than: Trigger alert when expression value greater than to threshold.
    • Less Than: Trigger alert when expression value equal or less than the threshold.
    • Greater or Equal: Trigger alert when expression value greater to equal to the threshold.
    • Less or Equal: Trigger alert when expression value less or equal to the threshold.

    If applicable, choose a comparison value or a threshold for the alert to be triggered.

    For​

    Select a duration for a trigger alert when the expression value crosses the threshold longer than the configured duration.

    Send a​

    Select the urgency level of the alert.

    • Critical: Most urgent
    • Warning: Normal urgency
    • Info: Least urgent

    Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a node's load expression sum(node_load5) / count(node_cpu_seconds_total{mode="system"}) raises above 0.6 deems an urgency of Info, but 1 deems an urgency of Critical.

    Advanced Options​

    By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

    • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
    • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
    • Repeat Wait Time: How long to wait before re-sending a given alert that has already been sent, default to 1 hour.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cluster-configuration.html b/v2.0-v2.4/pages-for-subheaders/cluster-configuration.html index 82bca3d7613..98332d2f622 100644 --- a/v2.0-v2.4/pages-for-subheaders/cluster-configuration.html +++ b/v2.0-v2.4/pages-for-subheaders/cluster-configuration.html @@ -5,13 +5,13 @@ Cluster Configuration | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Configuration

    After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster.

    For information on editing cluster membership, go to this page.

    Cluster Management Capabilities by Cluster Type​

    The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters provisioned by RKE have Cluster Options available for editing.

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher launched Kubernetes ClustersHosted Kubernetes ClustersImported Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓
    Managing Cluster Members✓✓✓
    Editing and Upgrading Clusters✓✓*
    Managing Nodes✓✓✓
    Managing Persistent Volumes and Storage Classes✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓
    Using App Catalogs✓✓✓
    Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓
    Cloning Clusters✓✓
    Ability to rotate certificates✓
    Ability to back up your Kubernetes Clusters✓
    Ability to recover and restore etcd✓
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓
    Running Security Scans✓
    Authorized Cluster Endpoint✓

    * Cluster configuration options can't be edited for imported clusters, except for K3s clusters.

    Editing Clusters in the Rancher UI​

    To edit your cluster, open the Global view, make sure the Clusters tab is selected, and then select ⋮ > Edit for the cluster that you want to edit.

    In clusters launched by RKE, you can edit any of the remaining options that follow.

    Note that these options are not available for imported clusters or hosted Kubernetes clusters.

    OptionDescription
    Kubernetes VersionThe version of Kubernetes installed on each cluster node. For more detail, see Upgrading Kubernetes.
    Network ProviderThe \container networking interface (CNI) that powers networking for your cluster.

    Note: You can only choose this option while provisioning your cluster. It cannot be edited later.
    Project Network IsolationAs of Rancher v2.0.7, if you're using the Canal network provider, you can choose whether to enable or disable inter-project communication.
    Nginx IngressIf you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster.
    Metrics Server MonitoringEach cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal.
    Pod Security Policy SupportEnables pod security policies for the cluster. After enabling this option, choose a policy using the Default Pod Security Policy drop-down.
    Docker version on nodesConfigures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a supported Docker version, Rancher will stop pods from running on nodes that don't have a supported Docker version installed.
    Docker Root DirectoryThe directory on your cluster nodes where you've installed Docker. If you install Docker on your nodes to a non-default directory, update this path.
    Default Pod Security PolicyIf you enable Pod Security Policy Support, use this drop-down to choose the pod security policy that's applied to the cluster.
    Cloud ProviderIf you're using a cloud provider to host cluster nodes launched by RKE, enable this option so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required.

    Editing Clusters with YAML​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

    • To edit an RKE config file directly from the Rancher UI, click Edit as YAML.
    • To read from an existing RKE file, click Read from File.

    image

    For an example of RKE config file syntax, see the RKE documentation.

    For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    In Rancher v2.0.0-v2.2.x, the config file is identical to the cluster config file for the Rancher Kubernetes Engine, which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the rancher_kubernetes_engine_config directive. For more information, see the cluster configuration reference.

    Note: In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: kube_api and kube_controller.

    Updating ingress-nginx​

    Clusters that were created before Kubernetes 1.16 will have an ingress-nginx updateStrategy of OnDelete. Clusters that were created with Kubernetes 1.16 or newer will have RollingUpdate.

    If the updateStrategy of ingress-nginx is OnDelete, you will need to delete these pods to get the correct version for your deployment.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cluster-logging.html b/v2.0-v2.4/pages-for-subheaders/cluster-logging.html index 97d4d02f75b..1513dd0ab94 100644 --- a/v2.0-v2.4/pages-for-subheaders/cluster-logging.html +++ b/v2.0-v2.4/pages-for-subheaders/cluster-logging.html @@ -5,13 +5,13 @@ Cluster Logging | Rancher Manager - +
    Version: v2.0-v2.4

    Cluster Logging

    Logging is helpful because it allows you to:

    • Capture and analyze the state of your cluster
    • Look for trends in your environment
    • Save your logs to a safe location outside of your cluster
    • Stay informed of events like a container crashing, a pod eviction, or a node dying
    • More easily debug and troubleshoot problems

    Rancher supports integration with the following services:

    • Elasticsearch
    • Splunk
    • Kafka
    • Syslog
    • Fluentd

    How Logging Integrations Work

    Rancher can integrate with popular external services used for event streams, telemetry, or search. These services can log errors and warnings in your Kubernetes infrastructure to a stream.

    These services collect container log events, which are saved to the /var/log/containers directory on each of your nodes. The service collects both standard and error events. You can then log into your services to review the events collected, leveraging each service's unique features.

    When configuring Rancher to integrate with these services, you'll have to point Rancher toward the service's endpoint and provide authentication information.

    Additionally, you'll have the opportunity to enter key-value pairs to filter the log events collected. The service will only collect events for containers marked with your configured key-value pairs.

    Note: You can only configure one logging service per cluster or per project.

    Requirements

    The Docker daemon on each node in the cluster should be configured with the (default) log-driver: json-file. You can check the log-driver by running the following command:

    $ docker info | grep 'Logging Driver'
    Logging Driver: json-file

    Logging Scope

    You can configure logging at either cluster level or project level.

    • Cluster logging writes logs for every pod in the cluster, i.e. in all the projects. For RKE clusters, it also writes logs for all the Kubernetes system components.
    • Project logging writes logs for every pod in that particular project.

    Logs that are sent to your logging service are from the following locations:

    • Pod logs stored at /var/log/containers.
    • Kubernetes system components logs stored at /var/lib/rancher/rke/log/.

    Enabling Cluster Logging

    As an administrator or cluster owner, you can configure Rancher to send Kubernetes logs to a logging service.

    1. From the Global view, navigate to the cluster that you want to configure cluster logging.

    2. Select Tools > Logging in the navigation bar.

    3. Select a logging service and enter the configuration. Refer to the specific service for detailed configuration. Rancher supports integration with the following services:

    4. (Optional) Instead of using the UI to configure the logging services, you can enter custom advanced configurations by clicking on Edit as File, which is located above the logging targets. This link is only visible after you select a logging service.

      • With the file editor, enter raw fluentd configuration for any logging service. Refer to the documentation for each logging service on how to setup the output configuration.

      • If the logging service is using TLS, you also need to complete the SSL Configuration form.

        1. Provide the Client Private Key and Client Certificate. You can either copy and paste them or upload them by using the Read from a file button.

          • You can use either a self-signed certificate or one provided by a certificate authority.

          • You can generate a self-signed certificate using an openssl command. For example:

            openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

        2. If you are using a self-signed certificate, provide the CA Certificate PEM.

    5. (Optional) Complete the Additional Logging Configuration form.

      1. Optional: Use the Add Field button to add custom log fields to your logging configuration. These fields are key value pairs (such as foo=bar) that you can use to filter the logs from another system.

      2. Enter a Flush Interval. This value determines how often Fluentd flushes data to the logging server. Intervals are measured in seconds.

      3. Include System Log. The logs from pods in system project and RKE components will be sent to the target. Uncheck it to exclude the system logs.

    6. Click Test. Rancher sends a test log to the service.

      Note: This button is replaced with Dry Run if you are using the custom configuration editor. In this case, Rancher calls the fluentd dry run command to validate the configuration.

    7. Click Save.

    Result: Rancher is now configured to send logs to the selected service. Log into the logging service so that you can start viewing the logs.

    Logging Architecture

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cluster-monitoring.html b/v2.0-v2.4/pages-for-subheaders/cluster-monitoring.html index af1c99cc0a1..56adbb08487 100644 --- a/v2.0-v2.4/pages-for-subheaders/cluster-monitoring.html +++ b/v2.0-v2.4/pages-for-subheaders/cluster-monitoring.html @@ -5,13 +5,13 @@ Integrating Rancher and Prometheus for Cluster Monitoring | Rancher Manager - +
    Version: v2.0-v2.4

    Integrating Rancher and Prometheus for Cluster Monitoring

    Available as of v2.2.0

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.

    About Prometheus

    Prometheus provides a time series of your data, which is, according to Prometheus documentation:

    You can configure these services to collect logs at either the cluster level or the project level. This page describes how to enable monitoring for a cluster. For details on enabling monitoring for a project, refer to the project administration section.

    A stream of timestamped values belonging to the same metric and the same set of labeled dimensions, along with comprehensive statistics and metrics of the monitored cluster.

    In other words, Prometheus lets you view metrics from your different Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus.

    By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, restore crashed servers, etc.

    Multi-tenancy support in terms of cluster-only and project-only Prometheus instances are also supported.

    Monitoring Scope

    Using Prometheus, you can monitor Rancher at both the cluster level and project level. For each cluster and project that is enabled for monitoring, Rancher deploys a Prometheus server.

    • Cluster monitoring allows you to view the health of your Kubernetes cluster. Prometheus collects metrics from the cluster components below, which you can view in graphs and charts.

      • Kubernetes control plane
      • etcd database
      • All nodes (including workers)

    • Project monitoring allows you to view the state of pods running in a given project. Prometheus collects metrics from the project's deployed HTTP and TCP/UDP workloads.

    Enabling Cluster Monitoring

    As an administrator or cluster owner, you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.

    Prerequisites: The following TCP ports need to be opened for metrics scraping:

    PortNode typeComponent
    9796WorkerNode exporter
    10254WorkerNginx Ingress Controller
    10250Worker/ControlplaneKubelet
    10251ControlplaneKube scheduler
    10252ControlplaneKube controller manager
    2379EtcdEtcd server

    Monitoring V1 requires a Kubernetes verison less than or equal to v1.20.x. To install monitoring on Kubernetes v1.21+, you will need to migrate to Monitoring V2.

    1. From the Global view, navigate to the cluster that you want to configure cluster monitoring.

    2. Select Tools > Monitoring in the navigation bar.

    3. Select Enable to show the Prometheus configuration options. Review the resource consumption recommendations to ensure you have enough resources for Prometheus and on your worker nodes to enable monitoring. Enter in your desired configuration options.

    4. Click Save.

    Result: The Prometheus server will be deployed as well as two monitoring applications. The two monitoring applications, cluster-monitoring and monitoring-operator, are added as an application to the cluster's system project. After the applications are active, you can start viewing cluster metrics through the Rancher dashboard or directly from Grafana.

    The default username and password for the Grafana instance will be admin/admin. However, Grafana dashboards are served via the Rancher authentication proxy, so only users who are currently authenticated into the Rancher server have access to the Grafana dashboard.

    Resource Consumption

    When enabling cluster monitoring, you need to ensure your worker nodes and Prometheus pod have enough resources. The tables below provides a guide of how much resource consumption will be used. In larger deployments, it is strongly advised that the monitoring infrastructure be placed on dedicated nodes in the cluster.

    Resource Consumption of Prometheus Pods​

    This table is the resource consumption of the Prometheus pod, which is based on the number of all the nodes in the cluster. The count of nodes includes the worker, control plane and etcd nodes. Total disk space allocation should be approximated by the rate * retention period set at the cluster level. When enabling cluster level monitoring, you should adjust the CPU and Memory limits and reservation.

    Number of Cluster NodesCPU (milli CPU)MemoryDisk
    5500650 MB~1 GB/Day
    5020002 GB~5 GB/Day
    25640006 GB~18 GB/Day

    Additional pod resource requirements for cluster level monitoring.

    WorkloadContainerCPU - RequestMem - RequestCPU - LimitMem - LimitConfigurable
    Prometheusprometheus750m750Mi1000m1000MiY
    prometheus-proxy50m50Mi100m100MiY
    prometheus-auth100m100Mi500m200MiY
    prometheus-config-reloader--50m50MiN
    rules-configmap-reloader--100m25MiN
    Grafanagrafana-init-plugin-json-copy50m50Mi50m50MiY
    grafana-init-plugin-json-modify50m50Mi50m50MiY
    grafana100m100Mi200m200MiY
    grafana-proxy50m50Mi100m100MiY
    Kube-State Exporterkube-state100m130Mi100m200MiY
    Node Exporterexporter-node200m200Mi200m200MiY
    Operatorprometheus-operator100m50Mi200m100MiY

    Resource Consumption of Other Pods​

    Besides the Prometheus pod, there are components that are deployed that require additional resources on the worker nodes.

    PodCPU (milli CPU)Memory (MB)
    Node Exporter (Per Node)10030
    Kube State Cluster Monitor100130
    Grafana100150
    Prometheus Cluster Monitoring Nginx5050
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/cluster-yml.html b/v2.0-v2.4/pages-for-subheaders/cluster-yml.html index db2e79ec036..d2e6e7957f8 100644 --- a/v2.0-v2.4/pages-for-subheaders/cluster-yml.html +++ b/v2.0-v2.4/pages-for-subheaders/cluster-yml.html @@ -5,13 +5,13 @@ cluster.yml Templates for RKE add-on installs | Rancher Manager - +
    Version: v2.0-v2.4

    cluster.yml Templates for RKE add-on installs

    These templates are intended to be used for RKE add-on installs, which are only supported up to Rancher v2.0.8. Please use the Rancher Helm chart if you are installing a newer Rancher version.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html b/v2.0-v2.4/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html index 9e7dbe7ff1f..341f9c1a07d 100644 --- a/v2.0-v2.4/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html +++ b/v2.0-v2.4/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html @@ -5,13 +5,13 @@ Configuring Microsoft Active Directory Federation Service (SAML) | Rancher Manager - +
    Version: v2.0-v2.4

    Configuring Microsoft Active Directory Federation Service (SAML)

    Available as of v2.0.7

    If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.

    Prerequisites​

    You must have Rancher installed.

    • Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the <RANCHER_SERVER> placeholder.
    • You must have a global administrator account on your Rancher installation.

    You must have a Microsoft AD FS Server configured.

    • Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the <AD_SERVER> placeholder.
    • You must have access to add Relying Party Trusts on your AD FS Server.

    Setup Outline​

    Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    Next: Configuring Microsoft AD FS for Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/configure-openldap.html b/v2.0-v2.4/pages-for-subheaders/configure-openldap.html index 3f51f12b4a1..94612690d7c 100644 --- a/v2.0-v2.4/pages-for-subheaders/configure-openldap.html +++ b/v2.0-v2.4/pages-for-subheaders/configure-openldap.html @@ -5,13 +5,13 @@ Configuring OpenLDAP | Rancher Manager - +
    Version: v2.0-v2.4

    Configuring OpenLDAP

    Available as of v2.0.5

    If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.

    Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. Log into the Rancher UI using the initial local admin account.
    2. From the Global view, navigate to Security > Authentication
    3. Select OpenLDAP. The Configure an OpenLDAP server form will be displayed.

    Test Authentication​

    Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.

    Note:

    The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step.

    1. Enter the username and password for the OpenLDAP account that should be mapped to the local principal account.
    2. Click Authenticate With OpenLDAP to test the OpenLDAP connection and finalise the setup.

    Result:

    • OpenLDAP authentication is configured.
    • The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account.

    Note:

    You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/configure-shibboleth-saml.html b/v2.0-v2.4/pages-for-subheaders/configure-shibboleth-saml.html index ffbfeb808f4..7ecf98afa7d 100644 --- a/v2.0-v2.4/pages-for-subheaders/configure-shibboleth-saml.html +++ b/v2.0-v2.4/pages-for-subheaders/configure-shibboleth-saml.html @@ -5,7 +5,7 @@ Configuring Shibboleth (SAML) | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.0-v2.4

    Configuring Shibboleth (SAML)

    Available as of v2.4.0

    If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.

    In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.

    The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to this page.

    Setting up Shibboleth in Rancher

    Shibboleth Prerequisites​

    • You must have a Shibboleth IdP Server configured.
    • Following are the Rancher Service Provider URLs needed for configuration: Metadata URL: https://<rancher-server>/v1-saml/shibboleth/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/shibboleth/saml/acs
    • Export a metadata.xml file from your IdP Server. For more information, see the Shibboleth documentation.

    Configure Shibboleth in Rancher​

    If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Shibboleth.

    3. Complete the Configure Shibboleth Account form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Rancher API Host: Enter the URL for your Rancher Server.

      6. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      7. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Shibboleth Account form, click Authenticate with Shibboleth, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.

      Note: You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.

    SAML Provider Caveats​

    If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.

    • There is no validation on users or groups when assigning permissions to them in Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.

    Setting up OpenLDAP in Rancher

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.

    OpenLDAP Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference. Note that nested group membership is not available for Shibboleth.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. Log into the Rancher UI using the initial local admin account.
    2. From the Global view, navigate to Security > Authentication
    3. Select OpenLDAP. The Configure an OpenLDAP server form will be displayed.

    Troubleshooting

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/create-kubernetes-persistent-storage.html b/v2.0-v2.4/pages-for-subheaders/create-kubernetes-persistent-storage.html index 0fdb38739e5..b982f2be223 100644 --- a/v2.0-v2.4/pages-for-subheaders/create-kubernetes-persistent-storage.html +++ b/v2.0-v2.4/pages-for-subheaders/create-kubernetes-persistent-storage.html @@ -5,13 +5,13 @@ Kubernetes Persistent Storage: Volumes and Storage Classes | Rancher Manager - +
    Version: v2.0-v2.4

    Kubernetes Persistent Storage: Volumes and Storage Classes

    When deploying an application that needs to retain data, you'll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application's pod fails.

    The documents in this section assume that you understand the Kubernetes concepts of persistent volumes, persistent volume claims, and storage classes. For more information, refer to the section on how storage works.

    Prerequisites​

    To set up persistent storage, the Manage Volumes role is required.

    If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    For provisioning new storage with Rancher, the cloud provider must be enabled. For details on enabling cloud providers, refer to this page.

    For attaching existing persistent storage to a cluster, the cloud provider does not need to be enabled.

    Setting up Existing Storage​

    The overall workflow for setting up existing storage is as follows:

    1. Set up your persistent storage. This may be storage in an infrastructure provider, or it could be your own storage.
    2. Add a persistent volume (PV) that refers to the persistent storage.
    3. Add a persistent volume claim (PVC) that refers to the PV.
    4. Mount the PVC as a volume in your workload.

    For details and prerequisites, refer to this page.

    Dynamically Provisioning New Storage in Rancher​

    The overall workflow for provisioning new storage is as follows:

    1. Add a StorageClass and configure it to use your storage provider. The StorageClass could refer to storage in an infrastructure provider, or it could refer to your own storage.
    2. Add a persistent volume claim (PVC) that refers to the storage class.
    3. Mount the PVC as a volume for your workload.

    For details and prerequisites, refer to this page.

    Longhorn Storage​

    Longhorn is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.

    Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI.

    If you have a pool of block storage, Longhorn can help you provide persistent storage to your Kubernetes cluster without relying on cloud providers. For more information about Longhorn features, refer to the documentation.

    Provisioning Storage Examples​

    We provide examples of how to provision storage with NFS, vSphere, and Amazon's EBS.

    GlusterFS Volumes​

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. For details on preventing this from happening, refer to this page.

    iSCSI Volumes​

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. For details on resolving this issue, refer to this page.

    hostPath Volumes​

    Before you create a hostPath volume, you need to set up an extra_bind in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/creating-a-vsphere-cluster.html b/v2.0-v2.4/pages-for-subheaders/creating-a-vsphere-cluster.html index d55e555efb2..d238c97c3d1 100644 --- a/v2.0-v2.4/pages-for-subheaders/creating-a-vsphere-cluster.html +++ b/v2.0-v2.4/pages-for-subheaders/creating-a-vsphere-cluster.html @@ -5,13 +5,13 @@ VSphere Node Template Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/deploy-rancher-manager.html b/v2.0-v2.4/pages-for-subheaders/deploy-rancher-manager.html index 8cbba571950..78c8967b391 100644 --- a/v2.0-v2.4/pages-for-subheaders/deploy-rancher-manager.html +++ b/v2.0-v2.4/pages-for-subheaders/deploy-rancher-manager.html @@ -5,13 +5,13 @@ Deploying Rancher Server | Rancher Manager - +
    Version: v2.0-v2.4

    Deploying Rancher Server

    Use one of the following guides to deploy and provision Rancher and a Kubernetes cluster in the provider of your choice.

    If you prefer, the following guide will take you through the same process in individual steps. Use this if you want to run Rancher in a different provider, on prem, or if you would just like to see how easy it is.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/deploy-rancher-workloads.html b/v2.0-v2.4/pages-for-subheaders/deploy-rancher-workloads.html index 8706349f683..ef83d3b680d 100644 --- a/v2.0-v2.4/pages-for-subheaders/deploy-rancher-workloads.html +++ b/v2.0-v2.4/pages-for-subheaders/deploy-rancher-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/downstream-cluster-configuration.html b/v2.0-v2.4/pages-for-subheaders/downstream-cluster-configuration.html index fcef4d52961..a13ab5e5333 100644 --- a/v2.0-v2.4/pages-for-subheaders/downstream-cluster-configuration.html +++ b/v2.0-v2.4/pages-for-subheaders/downstream-cluster-configuration.html @@ -5,13 +5,13 @@ Downstream Cluster Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/enable-experimental-features.html b/v2.0-v2.4/pages-for-subheaders/enable-experimental-features.html index 9e3cd477aff..186998de359 100644 --- a/v2.0-v2.4/pages-for-subheaders/enable-experimental-features.html +++ b/v2.0-v2.4/pages-for-subheaders/enable-experimental-features.html @@ -5,13 +5,13 @@ Enabling Experimental Features | Rancher Manager - +
    Version: v2.0-v2.4

    Enabling Experimental Features

    Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an unsupported storage type outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.

    The features can be enabled in three ways:

    Each feature has two values:

    • A default value, which can be configured with a flag or environment variable from the command line
    • A set value, which can be configured with the Rancher API or UI

    If no value has been set, Rancher uses the default value.

    Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.

    For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the feature flags page for more information.

    Enabling Features when Starting Rancher

    When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.

    Note: Values set from the Rancher API will override the value passed in through the command line.

    When installing Rancher with a Helm chart, use the --features option. In the below example, two features are enabled by passing the feature flag names names in a comma separated list:

    helm install rancher-latest/rancher \
      --name rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0

    Note: If you are installing an alpha version, Helm requires adding the --devel option to the command.

    Rendering the Helm Chart for Air Gap Installations​

    For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the air gap installation documentation.

    Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.

    The Helm 3 command is as follows:

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
      --namespace cattle-system \
      --set hostname=<RANCHER.YOURDOMAIN.COM> \
      --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
      --set ingress.tls.source=secret \
      --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
      --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
      --set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0

    The Helm 2 command is as follows:

    helm template ./rancher-<VERSION>.tgz --output-dir . \
      --name rancher \
      --namespace cattle-system \
      --set hostname=<RANCHER.YOURDOMAIN.COM> \
      --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
      --set ingress.tls.source=secret \
      --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Available as of v2.2.0, set a default private registry to be used in Rancher
      --set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts
      --set 'extraEnv[0].name=CATTLE_FEATURES' # Available as of v2.3.0
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true' # Available as of v2.3.0

    Enabling Features with the Rancher UI

    1. Go to the Global view and click Settings.
    2. Click the Feature Flags tab. You will see a list of experimental features.
    3. To enable a feature, go to the disabled feature you want to enable and click ⋮ > Activate.

    Result: The feature is enabled.

    Disabling Features with the Rancher UI​

    1. Go to the Global view and click Settings.
    2. Click the Feature Flags tab. You will see a list of experimental features.
    3. To disable a feature, go to the enabled feature you want to disable and click ⋮ > Deactivate.

    Result: The feature is disabled.

    Enabling Features with the Rancher API

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click True.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is enabled.

    Disabling Features with the Rancher API​

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click False.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is disabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm-charts-in-rancher.html b/v2.0-v2.4/pages-for-subheaders/helm-charts-in-rancher.html index 74fb084901d..ed355906faa 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm-charts-in-rancher.html +++ b/v2.0-v2.4/pages-for-subheaders/helm-charts-in-rancher.html @@ -5,13 +5,13 @@ Helm Charts in Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    Helm Charts in Rancher

    Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications.

    • Catalogs are GitHub repositories or Helm Chart repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called Helm charts.
    • Helm charts are a collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on.

    Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience.

    Catalog Scopes​

    Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects.

    ScopeDescriptionAvailable As of
    GlobalAll clusters and all projects can access the Helm charts in this catalogv2.0.0
    ClusterAll projects in the specific cluster can access the Helm charts in this catalogv2.2.0
    ProjectThis specific cluster can access the Helm charts in this catalogv2.2.0

    Catalog Helm Deployment Versions​

    Applicable as of v2.4.0

    In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully backwards compatible with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version. This will help reduce app deployment issues as your Rancher users will not need to know which version of your chart is compatible with which Helm version - they can just select a catalog, select an app and deploy a version that has already been vetted for compatibility.

    When you create a custom catalog, you will have to configure the catalog to use either Helm 2 or Helm 3. This version cannot be changed later. If the catalog is added with the wrong Helm version, it will need to be deleted and re-added.

    When you launch a new app from a catalog, the app will be managed by the catalog's Helm version. A Helm 2 catalog will use Helm 2 to manage all of the apps, and a Helm 3 catalog will use Helm 3 to manage all apps.

    By default, catalogs are assumed to be deployed using Helm 2. If you run an app in Rancher before v2.4.0, then upgrade to Rancher v2.4.0+, the app will still be managed by Helm 2. If the app was already using a Helm 3 Chart (API version 2) it will no longer work in v2.4.0+. You must either downgrade the chart's API version or recreate the catalog to use Helm 3.

    Charts that are specific to Helm 2 should only be added to a Helm 2 catalog, and Helm 3 specific charts should only be added to a Helm 3 catalog.

    When to use Helm 3​

    Applicable as of v2.4.0

    • If you want to ensure that the security permissions are being pulled from the kubeconfig file
    • If you want to utilize apiVersion v2 features such as creating a library chart to reduce code duplication, or moving your requirements from the requirements.yaml into the Chart.yaml

    Overall Helm 3 is a movement towards a more standardized Kubernetes feel. As the Kubernetes community has evolved, standards and best practices have as well. Helm 3 is an attempt to adopt those practices and streamline how charts are maintained.

    Helm 3 Backwards Compatibility​

    Applicable as of v2.4.0

    With the use of the OpenAPI schema to validate your rendered templates in Helm 3, you will find charts that worked in Helm 2 may not work in Helm 3. This will require you to update your chart templates to meet the new validation requirements. This is one of the main reasons support for Helm 2 and Helm 3 was provided starting in Rancher 2.4.x, as not all charts can be deployed immediately in Helm 3.

    Helm 3 does not create a namespace for you, so you will have to provide an existing one. This can cause issues if you have integrated code with Helm 2, as you will need to make code changes to ensure a namespace is being created and passed in for Helm 3. Rancher will continue to manage namespaces for Helm to ensure this does not impact your app deployment.

    apiVersion v2 is now reserved for Helm 3 charts. This apiVersion enforcement could cause issues as older versions of Helm 2 did not validate the apiVersion in the Chart.yaml file. In general, your Helm 2 chart’s apiVersion should be set to v1 and your Helm 3 chart’s apiVersion should be set to v2. You can install charts with apiVersion v1 with Helm 3, but you cannot install v2 charts into Helm 2.

    Built-in Global Catalogs​

    Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. For details, refer to the section on managing built-in global catalogs.

    Custom Catalogs​

    There are two types of catalogs in Rancher: Built-in global catalogs and custom catalogs.

    Any user can create custom catalogs to add into Rancher. Custom catalogs can be added into Rancher at the global level, cluster level, or project level. For details, refer to the section on adding custom catalogs and the catalog configuration reference.

    Creating and Launching Applications​

    In Rancher, applications are deployed from the templates in a catalog.

    Chart Compatibility with Rancher​

    Charts now support the fields rancher_min_version and rancher_max_version in the questions.yml file to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements.

    Global DNS​

    Available as v2.2.0

    When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS.

    For more information on how to use this feature, see Global DNS.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm-rancher.html b/v2.0-v2.4/pages-for-subheaders/helm-rancher.html index 78d71577880..9c93cb27be9 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm-rancher.html +++ b/v2.0-v2.4/pages-for-subheaders/helm-rancher.html @@ -5,14 +5,14 @@ 4. Install Rancher | Rancher Manager - +
    Version: v2.0-v2.4

    4. Install Rancher

    Rancher installation is managed using the Helm package manager for Kubernetes. Use helm to install the prerequisite and charts to install Rancher.

    For systems without direct internet access, see Air Gap: Kubernetes install.

    Refer to the Helm version requirements to choose a version of Helm to install Rancher.

    Note: The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to these instructions.

    Add the Helm Chart Repository​

    Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      Note: Upgrades are not supported to, from, or between Alphas.

    Choose your SSL Configuration​

    Rancher Server is designed to be secure by default and requires SSL/TLS configuration.

    There are three recommended options for the source of the certificate.

    Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

    ConfigurationChart optionDescriptionRequires cert-manager
    Rancher Generated Certificatesingress.tls.source=rancherUse certificates issued by Rancher's generated CA (self signed)
    This is the default    		yes
    Let’s Encryptingress.tls.source=letsEncryptUse Let's Encrypt to issue a certificateyes
    Certificates from Filesingress.tls.source=secretUse your own certificate files by creating Kubernetes Secret(s)no

    Optional: Install cert-manager​

    Note: cert-manager is only required for certificates issued by Rancher's generated CA (ingress.tls.source=rancher) and Let's Encrypt issued certificates (ingress.tls.source=letsEncrypt). You should skip this step if you are using your own certificate files (option ingress.tls.source=secret) or if you use TLS termination on an External Load Balancer.

    Important: Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.

    Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

    Rancher relies on cert-manager to issue certificates from Rancher's own generated CA or to request Let's Encrypt certificates.

    These instructions are adapted from the official cert-manager documentation.

    1. Install the CustomResourceDefinition resources separately

      kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.9/deploy/manifests/00-crds.yaml

    2. Create the namespace for cert-manager

      kubectl create namespace cert-manager

    3. Label the cert-manager namespace to disable resource validation

      kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true

    4. Add the Jetstack Helm repository

      helm repo add jetstack https://charts.jetstack.io

    5. Update your local Helm chart repository cache

      helm repo update

    6. Install the cert-manager Helm chart

      helm install \
        --name cert-manager \
        --namespace cert-manager \
        --version v0.14.2 \
        jetstack/cert-manager

    Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

    kubectl get pods --namespace cert-manager

    NAME                                            READY   STATUS      RESTARTS   AGE
    cert-manager-7cbdc48784-rpgnt                   1/1     Running     0          3m
    cert-manager-webhook-5b5dd6999-kst4x            1/1     Running     0          3m
    cert-manager-cainjector-3ba5cd2bcd-de332x       1/1     Running     0          3m

    If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check the troubleshooting guide.


    Rancher Generated Certificates​

    Note: You need to have cert-manager installed before proceeding.

    The default is for Rancher to generate a CA and uses cert-manager to issue the certificate for access to the Rancher server interface. Because rancher is the default option for ingress.tls.source, we are not specifying ingress.tls.source when running the helm install command.

    • Set the hostname to the DNS name you pointed at your load balancer.
    • If you are installing an alpha version, Helm requires adding the --devel option to the command.
    helm install rancher-<CHART_REPO>/rancher \
      --name rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org

    Wait for Rancher to be rolled out:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    Let's Encrypt​

    Note: You need to have cert-manager installed before proceeding.

    This option uses cert-manager to automatically request and renew Let's Encrypt certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. This configuration uses HTTP validation (HTTP-01) so the load balancer must have a public DNS record and be accessible from the internet.

    In the following command,

    • Set hostname to the public DNS record that resolves to your load balancer.
    • Set ingress.tls.source to letsEncrypt.
    • Set letsEncrypt.email to the email address used for communication about your certificate (for example, expiry notices).
    • Set letsEncrypt.ingress.class to whatever your ingress controller is, e.g., traefik, nginx, haproxy, etc.
    • If you are installing an alpha version, Helm requires adding the --devel option to the command.
    helm install rancher-<CHART_REPO>/rancher \
      --name rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set ingress.tls.source=letsEncrypt \
      --set letsEncrypt.email=me@example.org \
      --set letsEncrypt.ingress.class=nginx

    Wait for Rancher to be rolled out:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    Certificates from Files​

    Create Kubernetes secrets from your own certificates for Rancher to use.

    Note: The Common Name or a Subject Alternative Names entry in the server certificate must match the hostname option, or the ingress controller will fail to configure correctly. Although an entry in the Subject Alternative Names is technically required, having a matching Common Name maximizes compatibility with older browsers/applications. If you want to check if your certificates are correct, see How do I check Common Name and Subject Alternative Names in my server certificate?

    • Set hostname and set ingress.tls.source to secret.
    • If you are installing an alpha version, Helm requires adding the --devel option to the command.
    helm install rancher-<CHART_REPO>/rancher \
      --name rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set ingress.tls.source=secret

    If you are using a Private CA signed certificate , add --set privateCA=true to the command:

    helm install rancher-<CHART_REPO>/rancher \
      --name rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set ingress.tls.source=secret
      --set privateCA=true

    Now that Rancher is deployed, see Adding TLS Secrets to publish the certificate files so Rancher and the ingress controller can use them.

    After adding the secrets, check if Rancher was rolled out successfully:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    If you see the following error: error: deployment "rancher" exceeded its progress deadline, you can check the status of the deployment by running the following command:

    kubectl -n cattle-system get deploy rancher
    NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    rancher   3         3         3            3           3m

    It should show the same count for DESIRED and AVAILABLE.

    Advanced Configurations​

    The Rancher chart configuration has many options for customizing the install to suit your specific environment. Here are some common advanced scenarios.

    See the Chart Options for the full list of options.

    Save your options​

    Make sure you save the --set options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.

    Finishing Up​

    That's it you should have a functional Rancher server. Point a browser at the hostname you picked and you should be greeted by the colorful login page.

    Doesn't work? Take a look at the Troubleshooting Page

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-create-nodes-lb.html b/v2.0-v2.4/pages-for-subheaders/helm2-create-nodes-lb.html index 8ed17b8a2a3..b55c909041a 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-create-nodes-lb.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-create-nodes-lb.html @@ -5,14 +5,14 @@ 1. Create Nodes and Load Balancer | Rancher Manager - +
    Version: v2.0-v2.4

    1. Create Nodes and Load Balancer

    Use your provider of choice to provision 3 nodes and a Load Balancer endpoint for your RKE install.

    Note: These nodes must be in the same region/datacenter. You may place these servers in separate availability zones.

    Node Requirements​

    View the supported operating systems and hardware/software/networking requirements for nodes running Rancher at Node Requirements.

    View the OS requirements for RKE at RKE Requirements

    Load Balancer​

    RKE will configure an Ingress controller pod, on each of your nodes. The Ingress controller pods are bound to ports TCP/80 and TCP/443 on the host network and are the entry point for HTTPS traffic to the Rancher server.

    Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configuration will vary depending on your environment.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    Examples​

    Next: Install Kubernetes with RKE​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-helm-init.html b/v2.0-v2.4/pages-for-subheaders/helm2-helm-init.html index fed52d77bd9..4fd4ef5c30d 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-helm-init.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-helm-init.html @@ -5,13 +5,13 @@ Initialize Helm: Install the Tiller Service | Rancher Manager - +
    Version: v2.0-v2.4

    Initialize Helm: Install the Tiller Service

    Helm is the package management tool of choice for Kubernetes. Helm "charts" provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/. To be able to use Helm, the server-side component tiller needs to be installed on your cluster.

    For systems without direct internet access, see Helm - Air Gap for install details.

    Refer to the Helm version requirements to choose a version of Helm to install Rancher.

    Note: The installation instructions assume you are using Helm 2. The instructions will be updated for Helm 3 soon. In the meantime, if you want to use Helm 3, refer to these instructions.

    Install Tiller on the Cluster​

    Important: Due to an issue with Helm v2.12.0 and cert-manager, please use Helm v2.12.1 or higher.

    Helm installs the tiller service on your cluster to manage charts. Since RKE enables RBAC by default we will need to use kubectl to create a serviceaccount and clusterrolebinding so tiller has permission to deploy to the cluster.

    • Create the ServiceAccount in the kube-system namespace.
    • Create the ClusterRoleBinding to give the tiller account access to the cluster.
    • Finally use helm to install the tiller service
    kubectl -n kube-system create serviceaccount tiller

    kubectl create clusterrolebinding tiller \
      --clusterrole=cluster-admin \
      --serviceaccount=kube-system:tiller

    helm init --service-account tiller

    # Users in China: You will need to specify a specific tiller-image in order to initialize tiller.
    # The list of tiller image tags are available here: https://dev.aliyun.com/detail.html?spm=5176.1972343.2.18.ErFNgC&repoId=62085.
    # When initializing tiller, you'll need to pass in --tiller-image

    helm init --service-account tiller \
    --tiller-image registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:<tag>

    Note: Thistillerinstall has full cluster access, which should be acceptable if the cluster is dedicated to Rancher server. Check out the helm docs for restricting tiller access to suit your security requirements.

    Test your Tiller installation​

    Run the following command to verify the installation of tiller on your cluster:

    kubectl -n kube-system  rollout status deploy/tiller-deploy
    Waiting for deployment "tiller-deploy" rollout to finish: 0 of 1 updated replicas are available...
    deployment "tiller-deploy" successfully rolled out

    And run the following command to validate Helm can talk to the tiller service:

    helm version
    Client: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}
    Server: &version.Version{SemVer:"v2.12.1", GitCommit:"02a47c7249b1fc6d8fd3b94e6b4babf9d818144e", GitTreeState:"clean"}

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-kubernetes-rke.html b/v2.0-v2.4/pages-for-subheaders/helm2-kubernetes-rke.html index 4487845a7cf..6bbb000aec8 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-kubernetes-rke.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-kubernetes-rke.html @@ -5,14 +5,14 @@ 2. Install Kubernetes with RKE | Rancher Manager - +
    Version: v2.0-v2.4

    2. Install Kubernetes with RKE

    Use RKE to install Kubernetes with a high availability etcd configuration.

    Note: For systems without direct internet access see Air Gap: Kubernetes install for install details.

    Create the rancher-cluster.yml File​

    Using the sample below create the rancher-cluster.yml file. Replace the IP Addresses in the nodes list with the IP address or DNS names of the 3 nodes you created.

    Note: If your node has public and internal addresses, it is recommended to set the internal_address: so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the internal_address: if you want to use self-referencing security groups or firewalls.

    nodes:
      - address: 165.227.114.63
        internal_address: 172.16.22.12
        user: ubuntu
        role: [controlplane,worker,etcd]
      - address: 165.227.116.167
        internal_address: 172.16.32.37
        user: ubuntu
        role: [controlplane,worker,etcd]
      - address: 165.227.127.226
        internal_address: 172.16.42.73
        user: ubuntu
        role: [controlplane,worker,etcd]

    services:
      etcd:
        snapshot: true
        creation: 6h
        retention: 24h

    Common RKE Nodes Options​

    OptionRequiredDescription
    addressyesThe public DNS or IP address
    useryesA user that can run docker commands
    roleyesList of Kubernetes roles assigned to the node
    internal_addressnoThe private DNS or IP address for internal cluster traffic
    ssh_key_pathnoPath to SSH private key used to authenticate to the node (defaults to ~/.ssh/id_rsa)

    Advanced Configurations​

    RKE has many configuration options for customizing the install to suit your specific environment.

    Please see the RKE Documentation for the full list of options and capabilities.

    For tuning your etcd cluster for larger Rancher installations see the etcd settings guide.

    Run RKE​

    rke up --config ./rancher-cluster.yml

    When finished, it should end with the line: Finished building Kubernetes cluster successfully.

    Testing Your Cluster​

    RKE should have created a file kube_config_rancher-cluster.yml. This file has the credentials for kubectl and helm.

    Note: If you have used a different file name from rancher-cluster.yml, then the kube config file will be named kube_config_<FILE_NAME>.yml.

    You can copy this file to $HOME/.kube/config or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_rancher-cluster.yml.

    export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml

    Test your connectivity with kubectl and see if all your nodes are in Ready state.

    kubectl get nodes

    NAME                          STATUS    ROLES                      AGE       VERSION
    165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.13.5

    Check the Health of Your Cluster Pods​

    Check that all the required pods and containers are healthy are ready to continue.

    • Pods are in Running or Completed state.
    • READY column shows all the containers are running (i.e. 3/3) for pods with STATUS Running
    • Pods with STATUS Completed are run-once Jobs. For these pods READY should be 0/1.
    kubectl get pods --all-namespaces

    NAMESPACE       NAME                                      READY     STATUS      RESTARTS   AGE
    ingress-nginx   nginx-ingress-controller-tnsn4            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-tw2ht            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-v874b            1/1       Running     0          30s
    kube-system     canal-jp4hz                               3/3       Running     0          30s
    kube-system     canal-z2hg8                               3/3       Running     0          30s
    kube-system     canal-z6kpw                               3/3       Running     0          30s
    kube-system     kube-dns-7588d5b5f5-sf4vh                 3/3       Running     0          30s
    kube-system     kube-dns-autoscaler-5db9bbb766-jz2k6      1/1       Running     0          30s
    kube-system     metrics-server-97bc649d5-4rl2q            1/1       Running     0          30s
    kube-system     rke-ingress-controller-deploy-job-bhzgm   0/1       Completed   0          30s
    kube-system     rke-kubedns-addon-deploy-job-gl7t4        0/1       Completed   0          30s
    kube-system     rke-metrics-addon-deploy-job-7ljkc        0/1       Completed   0          30s
    kube-system     rke-network-plugin-deploy-job-6pbgj       0/1       Completed   0          30s

    Save Your Files​

    Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

    Save a copy of the following files in a secure location:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
    • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains credentials for full access to the cluster.

      The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Initialize Helm (Install tiller)​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-4-lb.html b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-4-lb.html index 213d317bed7..dbc60b13fe2 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-4-lb.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-4-lb.html @@ -5,7 +5,7 @@ Kubernetes Install with External Load Balancer (TCP/Layer 4) | Rancher Manager - + @@ -17,7 +17,7 @@ Create a self-signed certificate.

    • The certificate files must be in PE The base64 encoded string should be on the same line as tls.crt or tls.key, without any newline at the beginning, in between or at the end.

      Step Result: After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

      ---
      apiVersion: v1
      kind: Secret
      metadata:
          name: cattle-keys-ingress
          namespace: cattle-system
      type: Opaque
      data:
          tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
          tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

    • In kind: Secret with name: cattle-keys-server, replace <BASE64_CA> with the base64 encoded string of the CA Certificate file (usually called ca.pem or ca.crt).

      Note: The base64 encoded string should be on the same line as cacerts.pem, without any newline at the beginning, in between or at the end.

      • **Step Result:** The file should look like the example below (the base64 encoded string should be different):

      ```yaml
      ---
      apiVersion: v1
      kind: Secret
      metadata:
        name: cattle-keys-server
        namespace: cattle-system
      type: Opaque
      data:
        cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
      ```
      Option B—Bring Your Own Certificate: Signed by Recognized CA

      If you are using a Certificate Signed By A Recognized Certificate Authority, you will need to generate a base64 encoded string for the Certificate file and the Certificate Key file. Make sure that your certificate file includes all the intermediate certificates in the chain, the order of certificates in this case is first your own certificate, followed by the intermediates. Please refer to the documentation of your CSP (Certificate Service Provider) to see what intermediate certificate(s) need to be included.

      In the kind: Secret with name: cattle-keys-ingress:

      • Replace <BASE64_CRT> with the base64 encoded string of the Certificate file (usually called cert.pem or domain.crt)
      • Replace <BASE64_KEY> with the base64 encoded string of the Certificate Key file (usually called key.pem or domain.key)

      After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

      Note: The base64 encoded string should be on the same line as tls.crt or tls.key, without any newline at the beginning, in between or at the end.

      ---
      apiVersion: v1
      kind: Secret
      metadata:
        name: cattle-keys-ingress
        namespace: cattle-system
      type: Opaque
      data:
        tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM1RENDQWN5Z0F3SUJBZ0lKQUlHc25NeG1LeGxLTUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NVGd3TlRBMk1qRXdOREE1V2hjTk1UZ3dOekExTWpFd05EQTVXakFXTVJRdwpFZ1lEVlFRRERBdG9ZUzV5Ym1Ob2NpNXViRENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DCmdnRUJBTFJlMXdzekZSb2Rib2pZV05DSHA3UkdJaUVIMENDZ1F2MmdMRXNkUUNKZlcrUFEvVjM0NnQ3bSs3TFEKZXJaV3ZZMWpuY2VuWU5JSGRBU0VnU0ducWExYnhUSU9FaE0zQXpib3B0WDhjSW1OSGZoQlZETGdiTEYzUk0xaQpPM1JLTGdIS2tYSTMxZndjbU9zWGUwaElYQnpUbmxnM20vUzlXL3NTc0l1dDVwNENDUWV3TWlpWFhuUElKb21lCmpkS3VjSHFnMTlzd0YvcGVUalZrcVpuMkJHazZRaWFpMU41bldRV0pjcThTenZxTTViZElDaWlwYU9hWWQ3RFEKYWRTejV5dlF0YkxQNW4wTXpnOU43S3pGcEpvUys5QWdkWDI5cmZqV2JSekp3RzM5R3dRemN6VWtLcnZEb05JaQo0UFJHc01yclFNVXFSYjRSajNQOEJodEMxWXNDQXdFQUFhTTVNRGN3Q1FZRFZSMFRCQUl3QURBTEJnTlZIUThFCkJBTUNCZUF3SFFZRFZSMGxCQll3RkFZSUt3WUJCUVVIQXdJR0NDc0dBUVVGQndNQk1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0SUJBUUNKZm5PWlFLWkowTFliOGNWUW5Vdi9NZkRZVEJIQ0pZcGM4MmgzUGlXWElMQk1jWDhQRC93MgpoOUExNkE4NGNxODJuQXEvaFZYYy9JNG9yaFY5WW9jSEg5UlcvbGthTUQ2VEJVR0Q1U1k4S292MHpHQ1ROaDZ6Ci9wZTNqTC9uU0pYSjRtQm51czJheHFtWnIvM3hhaWpYZG9kMmd3eGVhTklvRjNLbHB2aGU3ZjRBNmpsQTM0MmkKVVlCZ09iN1F5KytRZWd4U1diSmdoSzg1MmUvUUhnU2FVSkN6NW1sNGc1WndnNnBTUXhySUhCNkcvREc4dElSYwprZDMxSk1qY25Fb1Rhc1Jyc1NwVmNGdXZyQXlXN2liakZyYzhienBNcE1obDVwYUZRcEZzMnIwaXpZekhwakFsCk5ZR2I2OHJHcjBwQkp3YU5DS2ErbCtLRTk4M3A3NDYwCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
        tls.key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBdEY3WEN6TVZHaDF1aU5oWTBJZW50RVlpSVFmUUlLQkMvYUFzU3gxQUlsOWI0OUQ5ClhmanEzdWI3c3RCNnRsYTlqV09keDZkZzBnZDBCSVNCSWFlcHJWdkZNZzRTRXpjRE51aW0xZnh3aVkwZCtFRlUKTXVCc3NYZEV6V0k3ZEVvdUFjcVJjamZWL0J5WTZ4ZDdTRWhjSE5PZVdEZWI5TDFiK3hLd2k2M21uZ0lKQjdBeQpLSmRlYzhnbWlaNk4wcTV3ZXFEWDJ6QVgrbDVPTldTcG1mWUVhVHBDSnFMVTNtZFpCWWx5cnhMTytvemx0MGdLCktLbG81cGgzc05CcDFMUG5LOUMxc3MvbWZRek9EMDNzck1Xa21oTDcwQ0IxZmIydCtOWnRITW5BYmYwYkJETnoKTlNRcXU4T2cwaUxnOUVhd3l1dEF4U3BGdmhHUGMvd0dHMExWaXdJREFRQUJBb0lCQUJKYUErOHp4MVhjNEw0egpwUFd5bDdHVDRTMFRLbTNuWUdtRnZudjJBZXg5WDFBU2wzVFVPckZyTnZpK2xYMnYzYUZoSFZDUEN4N1RlMDVxClhPa2JzZnZkZG5iZFQ2RjgyMnJleVByRXNINk9TUnBWSzBmeDVaMDQwVnRFUDJCWm04eTYyNG1QZk1vbDdya2MKcm9Kd09rOEVpUHZZekpsZUd0bTAwUm1sRysyL2c0aWJsOTVmQXpyc1MvcGUyS3ZoN2NBVEtIcVh6MjlpUmZpbApiTGhBamQwcEVSMjNYU0hHR1ZqRmF3amNJK1c2L2RtbDZURDhrSzFGaUtldmJKTlREeVNXQnpPbXRTYUp1K01JCm9iUnVWWG4yZVNoamVGM1BYcHZRMWRhNXdBa0dJQWxOWjRHTG5QU2ZwVmJyU0plU3RrTGNzdEJheVlJS3BWZVgKSVVTTHM0RUNnWUVBMmNnZUE2WHh0TXdFNU5QWlNWdGhzbXRiYi9YYmtsSTdrWHlsdk5zZjFPdXRYVzkybVJneQpHcEhUQ0VubDB0Z1p3T081T1FLNjdFT3JUdDBRWStxMDJzZndwcmgwNFZEVGZhcW5QNTBxa3BmZEJLQWpmanEyCjFoZDZMd2hLeDRxSm9aelp2VkowV0lvR1ZLcjhJSjJOWGRTUVlUanZUZHhGczRTamdqNFFiaEVDZ1lFQTFBWUUKSEo3eVlza2EvS2V2OVVYbmVrSTRvMm5aYjJ1UVZXazRXSHlaY2NRN3VMQVhGY3lJcW5SZnoxczVzN3RMTzJCagozTFZNUVBzazFNY25oTTl4WE4vQ3ZDTys5b2t0RnNaMGJqWFh6NEJ5V2lFNHJPS1lhVEFwcDVsWlpUT3ZVMWNyCm05R3NwMWJoVDVZb2RaZ3IwUHQyYzR4U2krUVlEWnNFb2lFdzNkc0NnWUVBcVJLYWNweWZKSXlMZEJjZ0JycGkKQTRFalVLMWZsSjR3enNjbGFKUDVoM1NjZUFCejQzRU1YT0kvSXAwMFJsY3N6em83N3cyMmpud09mOEJSM0RBMwp6ZTRSWDIydWw4b0hGdldvdUZOTTNOZjNaNExuYXpVc0F0UGhNS2hRWGMrcEFBWGthUDJkZzZ0TU5PazFxaUNHCndvU212a1BVVE84b1ViRTB1NFZ4ZmZFQ2dZQUpPdDNROVNadUlIMFpSSitIV095enlOQTRaUEkvUkhwN0RXS1QKajVFS2Y5VnR1OVMxY1RyOTJLVVhITXlOUTNrSjg2OUZPMnMvWk85OGg5THptQ2hDTjhkOWN6enI5SnJPNUFMTApqWEtBcVFIUlpLTFgrK0ZRcXZVVlE3cTlpaHQyMEZPb3E5OE5SZDMzSGYxUzZUWDNHZ3RWQ21YSml6dDAxQ3ZHCmR4VnVnd0tCZ0M2Mlp0b0RLb3JyT2hvdTBPelprK2YwQS9rNDJBOENiL29VMGpwSzZtdmxEWmNYdUF1QVZTVXIKNXJCZjRVYmdVYndqa1ZWSFR6LzdDb1BWSjUvVUxJWk1Db1RUNFprNTZXWDk4ZE93Q3VTVFpZYnlBbDZNS1BBZApTZEpuVVIraEpnSVFDVGJ4K1dzYnh2d0FkbWErWUhtaVlPRzZhSklXMXdSd1VGOURLUEhHCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==

      8. Configure FQDN​

      There are two references to <FQDN> in the config file (one in this step and one in the next). Both need to be replaced with the FQDN chosen in Configure DNS.

      In the kind: Ingress with name: cattle-ingress-http:

      After replacing <FQDN> with the FQDN chosen in Configure DNS, the file should look like the example below (rancher.yourdomain.com is the FQDN used in this example):

       ---
        apiVersion: extensions/v1beta1
        kind: Ingress
        metadata:
          namespace: cattle-system
          name: cattle-ingress-http
          annotations:
            nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
            nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
            nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
        spec:
          rules:
          - host: rancher.yourdomain.com
            http:
              paths:
              - backend:
                  serviceName: cattle-service
                  servicePort: 80
          tls:
          - secretName: cattle-keys-ingress
            hosts:
            - rancher.yourdomain.com

      Save the .yml file and close it.

      9. Configure Rancher version​

      The last reference that needs to be replaced is <RANCHER_VERSION>. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the GitHub README. Make sure the version is an actual version number, and not a named tag like stable or latest. The example below shows the version configured to v2.0.6.

            spec:
              serviceAccountName: cattle-admin
              containers:
              - image: rancher/rancher:v2.0.6
                imagePullPolicy: Always

      10. Back Up Your RKE Config File​

      After you close your .yml file, back it up to a secure location. You can use this file again when it's time to upgrade Rancher.

      11. Run RKE​

      With all configuration in place, use RKE to launch Rancher. You can complete this action by running the rke up command and using the --config parameter to point toward your config file.

      1. From your workstation, make sure rancher-cluster.yml and the downloaded rke binary are in the same directory.

      2. Open a Terminal instance. Change to the directory that contains your config file and rke.

      3. Enter one of the rke up commands listen below.

      rke up --config rancher-cluster.yml

      Step Result: The output should be similar to the snippet below:

      INFO[0000] Building Kubernetes cluster
      INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
      INFO[0000] [network] Deploying port listener containers
      INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
      ...
      INFO[0101] Finished building Kubernetes cluster successfully

      12. Back Up Auto-Generated Config File​

      During installation, RKE automatically generates a config file named kube_config_rancher-cluster.yml in the same directory as the RKE binary. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.

      What's Next?​

      You have a couple of options:


      FAQ and Troubleshooting​

      How Do I Know if My Certificates are in PEM Format?

      You can recognize the PEM format by the following traits:

      • The file begins with the following header:
        -----BEGIN CERTIFICATE-----
      • The header is followed by a long string of characters. Like, really long.
      • The file ends with a footer:
        -----END CERTIFICATE-----

      PEM Certificate Example:

      ----BEGIN CERTIFICATE----- MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV ... more lines VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END CERTIFICATE-----

      How Can I Encode My PEM Files in base64?

      To encode your certificates in base64:

      1. Change directory to where the PEM file resides.
      2. Run one of the following commands. Replace FILENAME with the name of your certificate.
        # MacOS cat FILENAME | base64 # Linux cat FILENAME | base64 -w0 # Windows certutil -encode FILENAME FILENAME.base64

      How Can I Verify My Generated base64 String For The Certificates?

      To decode your certificates in base64:

      1. Copy the generated base64 string.
      2. Run one of the following commands. Replace YOUR_BASE64_STRING with the previously copied base64 string.
        # MacOS echo YOUR_BASE64_STRING | base64 -D # Linux echo YOUR_BASE64_STRING | base64 -d # Windows certutil -decode FILENAME.base64 FILENAME.verify

      What is the Order of Certificates if I Want to Add My Intermediate(s)?

      The order of adding certificates is as follows:

      -----BEGIN CERTIFICATE----- %YOUR_CERTIFICATE% -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- %YOUR_INTERMEDIATE_CERTIFICATE% -----END CERTIFICATE-----

      How Do I Validate My Certificate Chain?

      You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. Theca.pem file must be the same as you added to the rancher/rancher container. When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

      Command:

      openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443 -servername rancher.yourdomain.com ... Verify return code: 0 (ok)
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-7-lb.html b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-7-lb.html index 46a1959d54f..0cf40435544 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-7-lb.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-layer-7-lb.html @@ -5,14 +5,14 @@ Kubernetes Install with External Load Balancer (HTTPS/Layer 7) | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Install with External Load Balancer (HTTPS/Layer 7)

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster's sole purpose is running pods for Rancher. The setup is based on:

      In an Kubernetes setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.

      Kubernetes Rancher install with layer 7 load balancer, depicting SSL termination at load balancer

      Rancher HA

      1. Provision Linux Hosts​

      Provision three Linux hosts according to our Requirements.

      2. Configure Load Balancer​

      When using a load balancer in front of Rancher, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header X-Forwarded-Proto: https, this redirect is disabled. This is the expected configuration when terminating SSL externally.

      The load balancer has to be configured to support the following:

      • WebSocket connections
      • SPDY / HTTP/2 protocols
      • Passing / setting the following headers:
      HeaderValueDescription
      HostFQDN used to reach Rancher.To identify the server requested by the client.
      X-Forwarded-ProtohttpsTo identify the protocol that a client used to connect to the load balancer.

      Note: If this header is present, rancher/rancher does not redirect HTTP to HTTPS.
      X-Forwarded-PortPort used to reach Rancher.To identify the protocol that client used to connect to the load balancer.
      X-Forwarded-ForIP of the client connection.To identify the originating IP address of a client.

      Health checks can be executed on the /healthz endpoint of the node, this will return HTTP 200.

      We have example configurations for the following load balancers:

      3. Configure DNS​

      Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., rancher.yourdomain.com).

      1. Log into your DNS server a create a DNS A record that points to the IP address of your load balancer.

      2. Validate that the DNS A is working correctly. Run the following command from any terminal, replacing HOSTNAME.DOMAIN.COM with your chosen FQDN:

        nslookup HOSTNAME.DOMAIN.COM

        Step Result: Terminal displays output similar to the following:

        $ nslookup rancher.yourdomain.com
        Server:         YOUR_HOSTNAME_IP_ADDRESS
        Address:        YOUR_HOSTNAME_IP_ADDRESS#53

        Non-authoritative answer:
        Name:   rancher.yourdomain.com
        Address: HOSTNAME.DOMAIN.COM

      4. Install RKE​

      RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.

      1. Follow the RKE Install instructions.

      2. Confirm that RKE is now executable by running the following command:

        rke --version

      5. Download RKE Config File Template​

      RKE uses a YAML config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.

      1. Download one of following templates, depending on the SSL certificate you're using.

        Advanced Config Options:

      1. Rename the file to rancher-cluster.yml.

      6. Configure Nodes​

      Once you have the rancher-cluster.yml config file template, edit the nodes section to point toward your Linux hosts.

      1. Open rancher-cluster.yml in your favorite text editor.

      2. Update the nodes section with the information of your Linux hosts.

        For each node in your cluster, update the following placeholders: IP_ADDRESS_X and USER. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run docker ps.

        Note:

        When using RHEL/CentOS, the SSH user can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565. See Operating System Requirements for RHEL/CentOS specific requirements.

        nodes:
            # The IP address or hostname of the node
        - address: IP_ADDRESS_1
            # User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
            # When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
            user: USER
            role: [controlplane,etcd,worker]
            # Path the SSH key that can be used to access to node with the specified user
            ssh_key_path: ~/.ssh/id_rsa
        - address: IP_ADDRESS_2
            user: USER
            role: [controlplane,etcd,worker]
            ssh_key_path: ~/.ssh/id_rsa
        - address: IP_ADDRESS_3
            user: USER
            role: [controlplane,etcd,worker]
            ssh_key_path: ~/.ssh/id_rsa

      3. Optional: By default, rancher-cluster.yml is configured to take backup snapshots of your data. To disable these snapshots, change the backup directive setting to false, as depicted below.

        services:
          etcd:
            backup: false

      7. Configure Certificates​

      For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

      Choose from the following options:

      Option A—Bring Your Own Certificate: Self-Signed

      Prerequisites: Create a self-signed certificate.

      • The certificate files must be in PEM format.
      • The certificate files must be encoded in base64.
      • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

      In kind: Secret with name: cattle-keys-ingress, replace <BASE64_CA> with the base64 encoded string of the CA Certificate file (usually called ca.pem or ca.crt)

      Note: The base64 encoded string should be on the same line as cacerts.pem, without any newline at the beginning, in between or at the end.

      After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

          ---
          apiVersion: v1
          kind: Secret
          metadata:
              name: cattle-keys-server
              namespace: cattle-system
          type: Opaque
          data:
              cacerts.pem: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNvRENDQVlnQ0NRRHVVWjZuMEZWeU16QU5CZ2txaGtpRzl3MEJBUXNGQURBU01SQXdEZ1lEVlFRRERBZDAKWlhOMExXTmhNQjRYRFRFNE1EVXdOakl4TURRd09Wb1hEVEU0TURjd05USXhNRFF3T1Zvd0VqRVFNQTRHQTFVRQpBd3dIZEdWemRDMWpZVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFNQmpBS3dQCndhRUhwQTdaRW1iWWczaTNYNlppVmtGZFJGckJlTmFYTHFPL2R0RUdmWktqYUF0Wm45R1VsckQxZUlUS3UzVHgKOWlGVlV4Mmo1Z0tyWmpwWitCUnFiZ1BNbk5hS1hocmRTdDRtUUN0VFFZdGRYMVFZS0pUbWF5NU45N3FoNTZtWQprMllKRkpOWVhHWlJabkdMUXJQNk04VHZramF0ZnZOdmJ0WmtkY2orYlY3aWhXanp2d2theHRUVjZlUGxuM2p5CnJUeXBBTDliYnlVcHlad3E2MWQvb0Q4VUtwZ2lZM1dOWmN1YnNvSjhxWlRsTnN6UjVadEFJV0tjSE5ZbE93d2oKaG41RE1tSFpwZ0ZGNW14TU52akxPRUc0S0ZRU3laYlV2QzlZRUhLZTUxbGVxa1lmQmtBZWpPY002TnlWQUh1dApuay9DMHpXcGdENkIwbkVDQXdFQUFUQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFHTCtaNkRzK2R4WTZsU2VBClZHSkMvdzE1bHJ2ZXdia1YxN3hvcmlyNEMxVURJSXB6YXdCdFJRSGdSWXVtblVqOGo4T0hFWUFDUEthR3BTVUsKRDVuVWdzV0pMUUV0TDA2eTh6M3A0MDBrSlZFZW9xZlVnYjQrK1JLRVJrWmowWXR3NEN0WHhwOVMzVkd4NmNOQQozZVlqRnRQd2hoYWVEQmdma1hXQWtISXFDcEsrN3RYem9pRGpXbi8walI2VDcrSGlaNEZjZ1AzYnd3K3NjUDIyCjlDQVZ1ZFg4TWpEQ1hTcll0Y0ZINllBanlCSTJjbDhoSkJqa2E3aERpVC9DaFlEZlFFVFZDM3crQjBDYjF1NWcKdE03Z2NGcUw4OVdhMnp5UzdNdXk5bEthUDBvTXl1Ty82Tm1wNjNsVnRHeEZKSFh4WTN6M0lycGxlbTNZQThpTwpmbmlYZXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
      Option B—Bring Your Own Certificate: Signed by Recognized CA

      If you are using a Certificate Signed By A Recognized Certificate Authority, you don't need to perform any step in this part.

      8. Configure FQDN​

      There is one reference to <FQDN> in the RKE config file. Replace this reference with the FQDN you chose in 3. Configure DNS.

      1. Open rancher-cluster.yml.

      2. In the kind: Ingress with name: cattle-ingress-http:

        Replace <FQDN> with the FQDN chosen in 3. Configure DNS.

        Step Result: After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

        apiVersion: extensions/v1beta1
          kind: Ingress
          metadata:
            namespace: cattle-system
            name: cattle-ingress-http
            annotations:
              nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
              nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
              nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
          spec:
            rules:
            - host: rancher.yourdomain.com
              http:
                paths:
                - backend:
                    serviceName: cattle-service
                    servicePort: 80
      1. Save the file and close it.

      9. Configure Rancher version​

      The last reference that needs to be replaced is <RANCHER_VERSION>. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the GitHub README. Make sure the version is an actual version number, and not a named tag like stable or latest. The example below shows the version configured to v2.0.6.

            spec:
              serviceAccountName: cattle-admin
              containers:
              - image: rancher/rancher:v2.0.6
                imagePullPolicy: Always

      10. Back Up Your RKE Config File​

      After you close your RKE config file, rancher-cluster.yml, back it up to a secure location. You can use this file again when it's time to upgrade Rancher.

      11. Run RKE​

      With all configuration in place, use RKE to launch Rancher. You can complete this action by running the rke up command and using the --config parameter to point toward your config file.

      1. From your workstation, make sure rancher-cluster.yml and the downloaded rke binary are in the same directory.

      2. Open a Terminal instance. Change to the directory that contains your config file and rke.

      3. Enter one of the rke up commands listen below.

        rke up --config rancher-cluster.yml

        Step Result: The output should be similar to the snippet below:

        INFO[0000] Building Kubernetes cluster
        INFO[0000] [dialer] Setup tunnel for host [1.1.1.1]
        INFO[0000] [network] Deploying port listener containers
        INFO[0000] [network] Pulling image [alpine:latest] on host [1.1.1.1]
        ...
        INFO[0101] Finished building Kubernetes cluster successfully

      12. Back Up Auto-Generated Config File​

      During installation, RKE automatically generates a config file named kube_config_rancher-cluster.yml in the same directory as the rancher-cluster.yml file. Copy this file and back it up to a safe location. You'll use this file later when upgrading Rancher Server.

      What's Next?​


      FAQ and Troubleshooting​

      How Do I Know if My Certificates are in PEM Format?

      You can recognize the PEM format by the following traits:

      • The file begins with the following header:
        -----BEGIN CERTIFICATE-----
      • The header is followed by a long string of characters. Like, really long.
      • The file ends with a footer:
        -----END CERTIFICATE-----

      PEM Certificate Example:

      ----BEGIN CERTIFICATE----- MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV ... more lines VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg== -----END CERTIFICATE-----

      How Can I Encode My PEM Files in base64?

      To encode your certificates in base64:

      1. Change directory to where the PEM file resides.
      2. Run one of the following commands. Replace FILENAME with the name of your certificate.
        # MacOS cat FILENAME | base64 # Linux cat FILENAME | base64 -w0 # Windows certutil -encode FILENAME FILENAME.base64

      How Can I Verify My Generated base64 String For The Certificates?

      To decode your certificates in base64:

      1. Copy the generated base64 string.
      2. Run one of the following commands. Replace YOUR_BASE64_STRING with the previously copied base64 string.
        # MacOS echo YOUR_BASE64_STRING | base64 -D # Linux echo YOUR_BASE64_STRING | base64 -d # Windows certutil -decode FILENAME.base64 FILENAME.verify

      What is the Order of Certificates if I Want to Add My Intermediate(s)?

      The order of adding certificates is as follows:

      -----BEGIN CERTIFICATE----- %YOUR_CERTIFICATE% -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- %YOUR_INTERMEDIATE_CERTIFICATE% -----END CERTIFICATE-----

      How Do I Validate My Certificate Chain?

      You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. Theca.pem file must be the same as you added to the rancher/rancher container. When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

      Command:

      openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443 -servername rancher.yourdomain.com ... Verify return code: 0 (ok)
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-troubleshooting.html b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-troubleshooting.html index 3de1a5abfbc..0f4fe3c99be 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-troubleshooting.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on-troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting HA RKE Add-On Install | Rancher Manager - +
      Version: v2.0-v2.4

      Troubleshooting HA RKE Add-On Install

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher Helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      This section contains common errors seen when setting up a Kubernetes installation.

      Choose from the following options:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on.html b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on.html index 3599bc4365e..6f98d4ea53e 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2-rke-add-on.html @@ -5,13 +5,13 @@ RKE Add-On Install | Rancher Manager - +
      Version: v2.0-v2.4

      RKE Add-On Install

      Important: RKE add-on install is only supported up to Rancher v2.0.8​

      Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the helm chart.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/helm2.html b/v2.0-v2.4/pages-for-subheaders/helm2.html index f5d3a777cbf..14216c2cd50 100644 --- a/v2.0-v2.4/pages-for-subheaders/helm2.html +++ b/v2.0-v2.4/pages-for-subheaders/helm2.html @@ -5,13 +5,13 @@ Kubernetes Installation Using Helm 2 | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Installation Using Helm 2

      After Helm 3 was released, the Rancher installation instructions were updated to use Helm 3.

      If you are using Helm 2, we recommend migrating to Helm 3 because it is simpler to use and more secure than Helm 2.

      This section provides a copy of the older high-availability Kubernetes Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

      For production environments, we recommend installing Rancher in a high-availability configuration so that your user base can always access Rancher Server. When installed in a Kubernetes cluster, Rancher will integrate with the cluster's etcd database and take advantage of Kubernetes scheduling for high-availability.

      This procedure walks you through setting up a 3-node cluster with Rancher Kubernetes Engine (RKE) and installing the Rancher chart with the Helm package manager.

      Important: The Rancher management server can only be run on an RKE-managed Kubernetes cluster. Use of Rancher on hosted Kubernetes or other providers is not supported.

      Important: For the best performance, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

      • DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
      • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
      • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
      • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
      Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers

      High-availability Kubernetes Install

      Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers

      Required Tools​

      The following CLI tools are required for this install. Please make sure these tools are installed and available in your $PATH

      • kubectl - Kubernetes command-line tool.
      • rke - Rancher Kubernetes Engine, cli for building Kubernetes clusters.
      • helm - Package management for Kubernetes. Refer to the Helm version requirements to choose a version of Helm to install Rancher.

      Installation Outline​

      Additional Install Options​

      Previous Methods​

      RKE add-on install

      Important: RKE add-on install is only supported up to Rancher v2.0.8

      Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install .

      If you are currently using the RKE add-on install method, see Migrating from a Kubernetes Install with an RKE Add-on for details on how to move to using the Helm chart.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/horizontal-pod-autoscaler.html b/v2.0-v2.4/pages-for-subheaders/horizontal-pod-autoscaler.html index be7696596e8..765ee1d5864 100644 --- a/v2.0-v2.4/pages-for-subheaders/horizontal-pod-autoscaler.html +++ b/v2.0-v2.4/pages-for-subheaders/horizontal-pod-autoscaler.html @@ -5,14 +5,14 @@ The Horizontal Pod Autoscaler | Rancher Manager - +
      Version: v2.0-v2.4

      The Horizontal Pod Autoscaler

      The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down.

      Rancher provides some additional features to help manage HPAs, depending on the version of Rancher.

      You can create, manage, and delete HPAs using the Rancher UI in Rancher v2.3.0-alpha4 and higher versions. It only supports HPA in the autoscaling/v2beta2 API.

      Managing HPAs​

      The way that you manage HPAs is different based on your version of the Kubernetes API:

      • For Kubernetes API version autoscaling/V2beta1: This version of the Kubernetes API lets you autoscale your pods based on the CPU and memory utilization of your application.
      • For Kubernetes API Version autoscaling/V2beta2: This version of the Kubernetes API lets you autoscale your pods based on CPU and memory utilization, in addition to custom metrics.

      HPAs are also managed differently based on your version of Rancher:

      You might have additional HPA installation steps if you are using an older version of Rancher:

      • For Rancher v2.0.7+: Clusters created in Rancher v2.0.7 and higher automatically have all the requirements needed (metrics-server and Kubernetes cluster configuration) to use HPA.
      • For Rancher Before v2.0.7: Clusters created in Rancher before v2.0.7 don't automatically have the requirements needed to use HPA. For instructions on installing HPA for these clusters, refer to Manual HPA Installation for Clusters Created Before Rancher v2.0.7.

      Testing HPAs with a Service Deployment​

      In Rancher v2.3.x+, you can see your HPA's current number of replicas by going to your project and clicking Resources > HPA. For more information, refer to Get HPA Metrics and Status.

      You can also use kubectl to get the status of HPAs that you test with your load testing tool. For more information, refer to [Testing HPAs with kubectl] (k8s-in-rancher/horitzontal-pod-autoscaler/testing-hpa/).

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/infrastructure-setup.html b/v2.0-v2.4/pages-for-subheaders/infrastructure-setup.html index 6cccff215d2..ffb757d64b3 100644 --- a/v2.0-v2.4/pages-for-subheaders/infrastructure-setup.html +++ b/v2.0-v2.4/pages-for-subheaders/infrastructure-setup.html @@ -5,13 +5,13 @@ Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
      Version: v2.0-v2.4

      Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials.

      To set up infrastructure for a high-availability K3s Kubernetes cluster with an external DB, refer to this page.

      To set up infrastructure for a high-availability RKE Kubernetes cluster, refer to this page.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/install-cluster-autoscaler.html b/v2.0-v2.4/pages-for-subheaders/install-cluster-autoscaler.html index 09e05b432bb..439e49dacff 100644 --- a/v2.0-v2.4/pages-for-subheaders/install-cluster-autoscaler.html +++ b/v2.0-v2.4/pages-for-subheaders/install-cluster-autoscaler.html @@ -5,13 +5,13 @@ Cluster Autoscaler | Rancher Manager - +
      Version: v2.0-v2.4

      Cluster Autoscaler

      In this section, you'll learn how to install and use the Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

      The cluster autoscaler is a tool that automatically adjusts the size of the Kubernetes cluster when one of the following conditions is true:

      • There are pods that failed to run in the cluster due to insufficient resources.
      • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes.

      To prevent your pod from being evicted, set a priorityClassName: system-cluster-critical property on your pod spec.

      Cluster Autoscaler is designed to run on Kubernetes master nodes. It can run in the kube-system namespace. Cluster Autoscaler doesn't scale down nodes with non-mirrored kube-system pods running on them.

      It's possible to run a customized deployment of Cluster Autoscaler on worker nodes, but extra care needs to be taken to ensure that Cluster Autoscaler remains up and running.

      Cloud Providers

      Cluster Autoscaler provides support to distinct cloud providers. For more information, go to cluster-autoscaler supported cloud providers.

      Setting up Cluster Autoscaler on Amazon Cloud Provider​

      For details on running the cluster autoscaler on Amazon cloud provider, refer to this page.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html b/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html index ce33a213abf..fc07721723c 100644 --- a/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html +++ b/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html @@ -5,13 +5,13 @@ Install Rancher on a Kubernetes Cluster | Rancher Manager - +
      Version: v2.0-v2.4

      Prerequisite

      Set up the Rancher server's local Kubernetes cluster.

      The cluster requirements depend on the Rancher version:

      • In Rancher v2.4.x, Rancher needs to be installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.
      • In Rancher before v2.4, Rancher needs to be installed on an RKE Kubernetes cluster.

      For the tutorial to install an RKE Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE cluster, refer to this page.

      For the tutorial to install a K3s Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability K3s cluster, refer to this page.

      Install the Rancher Helm Chart

      Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents.

      With Helm, we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

      For systems without direct internet access, see Air Gap: Kubernetes install.

      To choose a Rancher version to install, refer to Choosing a Rancher Version.

      To choose a version of Helm to install Rancher with, refer to the Helm version requirements

      Note: The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. This section provides a copy of the older installation instructions for Rancher installed on an RKE Kubernetes cluster with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

      To set up Rancher,

      1. Install the required CLI tools
      2. Add the Helm chart repository
      3. Create a namespace for Rancher
      4. Choose your SSL configuration
      5. Install cert-manager (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
      6. Install Rancher with Helm and your chosen certificate option
      7. Verify that the Rancher server is successfully deployed
      8. Save your options

      1. Install the Required CLI Tools​

      The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your $PATH.

      Refer to the instructions provided by the Helm project for your specific platform.

      2. Add the Helm Chart Repository​

      Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

      • Latest: Recommended for trying out the newest features
        helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
      • Stable: Recommended for production environments
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      • Alpha: Experimental preview of upcoming releases.
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
        Note: Upgrades are not supported to, from, or between Alphas.

      3. Create a Namespace for Rancher​

      We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system:

      kubectl create namespace cattle-system

      4. Choose your SSL Configuration​

      The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.

      Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

      There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:

      • Rancher-generated TLS certificate: In this case, you will need to install cert-manager into the cluster. Rancher utilizes cert-manager to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. cert-manager is then responsible for managing that certificate.
      • Let's Encrypt: The Let's Encrypt option also uses cert-manager. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (HTTP-01), so the load balancer must have a public DNS record and be accessible from the internet.
      • Bring your own certificate: This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name tls.crt and tls.key. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
      ConfigurationHelm Chart OptionRequires cert-manager
      Rancher Generated Certificates (Default)ingress.tls.source=rancheryes
      Let’s Encryptingress.tls.source=letsEncryptyes
      Certificates from Filesingress.tls.source=secretno

      5. Install cert-manager​

      You should skip this step if you are bringing your own certificate files (option ingress.tls.source=secret), or if you use TLS termination on an external load balancer.

      This step is only required to use certificates issued by Rancher's generated CA (ingress.tls.source=rancher) or to request Let's Encrypt issued certificates (ingress.tls.source=letsEncrypt).

      Click to Expand

      Important: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade documentation.

      These instructions are adapted from the official cert-manager documentation.

      # Install the CustomResourceDefinition resources separately
      kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.4/cert-manager.crds.yaml

      # **Important:**
      # If you are running Kubernetes v1.15 or below, you
      # will need to add the `--validate=false` flag to your
      # kubectl apply command, or else you will receive a
      # validation error relating to the
      # x-kubernetes-preserve-unknown-fields field in
      # cert-manager’s CustomResourceDefinition resources.
      # This is a benign error and occurs due to the way kubectl
      # performs resource validation.

      # Create the namespace for cert-manager
      kubectl create namespace cert-manager

      # Add the Jetstack Helm repository
      helm repo add jetstack https://charts.jetstack.io

      # Update your local Helm chart repository cache
      helm repo update

      # Install the cert-manager Helm chart
      helm install \
        cert-manager jetstack/cert-manager \
        --namespace cert-manager \
        --version v1.0.4

      Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

      kubectl get pods --namespace cert-manager

      NAME                                       READY   STATUS    RESTARTS   AGE
      cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
      cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
      cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

      6. Install Rancher with Helm and Your Chosen Certificate Option​

      The exact command to install Rancher differs depending on the certificate configuration.

      The default is for Rancher to generate a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.

      Because rancher is the default option for ingress.tls.source, we are not specifying ingress.tls.source when running the helm install command.

      • Set the hostname to the DNS name you pointed at your load balancer.
      • If you are installing an alpha version, Helm requires adding the --devel option to the command.
      • To install a specific Rancher version, use the --version flag, example: --version 2.3.6
      helm install rancher rancher-<CHART_REPO>/rancher \
        --namespace cattle-system \
        --set hostname=rancher.my.org

      Wait for Rancher to be rolled out:

      kubectl -n cattle-system rollout status deploy/rancher
      Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
      deployment "rancher" successfully rolled out

      The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.

      See the Chart Options for the full list of options.

      7. Verify that the Rancher Server is Successfully Deployed​

      After adding the secrets, check if Rancher was rolled out successfully:

      kubectl -n cattle-system rollout status deploy/rancher
      Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
      deployment "rancher" successfully rolled out

      If you see the following error: error: deployment "rancher" exceeded its progress deadline, you can check the status of the deployment by running the following command:

      kubectl -n cattle-system get deploy rancher
      NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
      rancher   3         3         3            3           3m

      It should show the same count for DESIRED and AVAILABLE.

      8. Save Your Options​

      Make sure you save the --set options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.

      Finishing Up​

      That's it. You should have a functional Rancher server.

      In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.

      Doesn't work? Take a look at the Troubleshooting Page

      Optional Next Steps​

      Enable the Enterprise Cluster Manager.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade.html b/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade.html index 1eaca533aaa..950bb3844cf 100644 --- a/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade.html +++ b/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade.html @@ -5,14 +5,14 @@ Installing/Upgrading Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Installing/Upgrading Rancher

      This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.

      Terminology

      In this section,

      • The Rancher server manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface.
      • RKE (Rancher Kubernetes Engine) is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster.
      • K3s (Lightweight Kubernetes) is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB. As of Rancher v2.4, Rancher can be installed on a K3s cluster.

      Overview of Installation Options

      Rancher can be installed on these main architectures:

      High-availability Kubernetes Install with the Helm CLI​

      We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required.

      Single-node Kubernetes Install​

      Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't have high availability, which is important for running Rancher in production.

      However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server.

      Docker Install​

      For test and demonstration purposes, Rancher can be installed with Docker on a single node.

      For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.

      Other Options​

      There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy:

      Level of Internet AccessKubernetes Installation - Strongly RecommendedDocker Installation
      With direct access to the InternetDocsDocs
      Behind an HTTP proxyThese docs, plus this configurationThese docs, plus this configuration
      In an air gap environmentDocsDocs

      We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage.

      For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters.

      The type of cluster that Rancher needs to be installed on depends on the Rancher version.

      For Rancher v2.4.x, either an RKE Kubernetes cluster or K3s Kubernetes cluster can be used. For Rancher before v2.4, an RKE cluster must be used.

      For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only.

      Our instructions for installing Rancher on Kubernetes describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster.

      When the nodes in your Kubernetes cluster are running and fulfill the node requirements, you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster.

      For a longer discussion of Rancher architecture, refer to the architecture overview, recommendations for production-grade architecture, or our best practices guide.

      Prerequisites

      Before installing Rancher, make sure that your nodes fulfill all of the installation requirements.

      Architecture Tip

      For the best performance and greater security, we recommend a separate, dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

      For more architecture recommendations, refer to this page.

      More Options for Installations on a Kubernetes Cluster​

      Refer to the Helm chart options for details on installing Rancher on a Kubernetes cluster with other configurations, including:

      In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation:

      More Options for Installations with Docker​

      Refer to the docs about options for Docker installs for details about other configurations including:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/installation-references.html b/v2.0-v2.4/pages-for-subheaders/installation-references.html index a76b18ef5fb..7a6d32a9b6a 100644 --- a/v2.0-v2.4/pages-for-subheaders/installation-references.html +++ b/v2.0-v2.4/pages-for-subheaders/installation-references.html @@ -5,13 +5,13 @@ Installation References | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/installation-requirements.html b/v2.0-v2.4/pages-for-subheaders/installation-requirements.html index bee744b2212..7dabcd5c2ee 100644 --- a/v2.0-v2.4/pages-for-subheaders/installation-requirements.html +++ b/v2.0-v2.4/pages-for-subheaders/installation-requirements.html @@ -5,13 +5,13 @@ Installation Requirements | Rancher Manager - +
      Version: v2.0-v2.4

      Installation Requirements

      This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.

      It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the node requirements for downstream user clusters, which will run your apps and services.

      Make sure the node(s) for the Rancher server fulfill the following requirements:

      For a list of best practices that we recommend for running the Rancher server in production, refer to the best practices section.

      The Rancher UI works best in Firefox or Chrome.

      Operating Systems and Container Runtime Requirements

      Rancher should work with any modern Linux distribution.

      For details on which OS, Docker, and Kubernetes versions were tested with each Rancher version, refer to the support maintenance terms.

      All supported operating systems are 64-bit x86.

      The ntp (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.

      Some distributions of Linux may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.

      If you plan to run Rancher on ARM64, see Running on ARM64 (Experimental).

      RKE Specific Requirements​

      For the container runtime, RKE should work with any modern Docker version.

      K3s Specific Requirements​

      For the container runtime, K3s should work with any modern version of Docker or containerd.

      Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

      If you are installing Rancher on a K3s cluster with Raspbian Buster, follow these steps to switch to legacy iptables.

      If you are installing Rancher on a K3s cluster with Alpine Linux, follow these steps for additional setup.

      Installing Docker​

      Docker is required for Helm chart installs, and it can be installed by following the steps in the official Docker documentation. Rancher also provides scripts to install Docker with one command.

      Hardware Requirements

      This section describes the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.

      CPU and Memory​

      Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.

      These requirements apply to each host in an RKE Kubernetes cluster where the Rancher server is installed.

      Performance increased in Rancher v2.4.0. For the requirements of Rancher before v2.4.0, refer to this section.

      Deployment SizeClustersNodesvCPUsRAM
      SmallUp to 150Up to 150028 GB
      MediumUp to 300Up to 3000416 GB
      LargeUp to 500Up to 5000832 GB
      X-LargeUp to 1000Up to 10,0001664 GB
      XX-LargeUp to 2000Up to 20,00032128 GB

      Every use case and environment is different. Please contact Rancher to review yours.

      CPU and Memory for Rancher before v2.4.0​

      Click to expand

      These requirements apply to installing Rancher on an RKE Kubernetes cluster before Rancher v2.4.0:

      Deployment SizeClustersNodesvCPUsRAM
      SmallUp to 5Up to 5028 GB
      MediumUp to 15Up to 200416 GB
      LargeUp to 50Up to 500832 GB
      X-LargeUp to 100Up to 100032128 GB
      XX-Large100+1000+Contact RancherContact Rancher

      Disks​

      Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.

      Networking Requirements

      This section describes the networking requirements for the node(s) where the Rancher server is installed.

      Node IP Addresses​

      Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

      Port Requirements​

      To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. Port Requirements lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/integrations-in-rancher.html b/v2.0-v2.4/pages-for-subheaders/integrations-in-rancher.html index 2f7b809d6b7..1abab773feb 100644 --- a/v2.0-v2.4/pages-for-subheaders/integrations-in-rancher.html +++ b/v2.0-v2.4/pages-for-subheaders/integrations-in-rancher.html @@ -5,13 +5,13 @@ Integrations in Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Integrations in Rancher

      Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI.

      Examples of some of these integrations are Istio and CIS Scans.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/introduction.html b/v2.0-v2.4/pages-for-subheaders/introduction.html index 6b553cee6d0..d7892b9ca40 100644 --- a/v2.0-v2.4/pages-for-subheaders/introduction.html +++ b/v2.0-v2.4/pages-for-subheaders/introduction.html @@ -5,13 +5,13 @@ Introduction | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/istio-setup-guide.html b/v2.0-v2.4/pages-for-subheaders/istio-setup-guide.html index 8803c491a15..ca2f81e4583 100644 --- a/v2.0-v2.4/pages-for-subheaders/istio-setup-guide.html +++ b/v2.0-v2.4/pages-for-subheaders/istio-setup-guide.html @@ -5,13 +5,13 @@ Setup Guide | Rancher Manager - +
      Version: v2.0-v2.4

      Setup Guide

      This section describes how to enable Istio and start using it in your projects.

      This section assumes that you have Rancher installed, and you have a Rancher-provisioned Kubernetes cluster where you would like to set up Istio.

      If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.

      Quick Setup If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for setting up the Istio gateway and setting up Istio's components for traffic management.

      1. Enable Istio in the cluster.
      2. Enable Istio in all the namespaces where you want to use it.
      3. Select the nodes where the main Istio components will be deployed.
      4. Add deployments and services that have the Istio sidecar injected.
      5. Set up the Istio gateway.
      6. Set up Istio's components for traffic management.
      7. Generate traffic and see Istio in action.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/istio.html b/v2.0-v2.4/pages-for-subheaders/istio.html index b36e54ed4fa..a67055b1a5e 100644 --- a/v2.0-v2.4/pages-for-subheaders/istio.html +++ b/v2.0-v2.4/pages-for-subheaders/istio.html @@ -5,13 +5,13 @@ Istio | Rancher Manager - +
      Version: v2.0-v2.4

      Istio

      Available as of v2.3.0

      Istio is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.

      As a network of microservices changes and grows, the interactions between them can become more difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.

      Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

      This service mesh provides features that include but are not limited to the following:

      • Traffic management features
      • Enhanced monitoring and tracing
      • Service discovery and routing
      • Secure connections and service-to-service authentication with mutual TLS
      • Load balancing
      • Automatic retries, backoff, and circuit breaking

      After Istio is enabled in a cluster, you can leverage Istio's control plane functionality with kubectl.

      Rancher's Istio integration comes with comprehensive visualization aids:

      • Trace the root cause of errors with Jaeger. Jaeger is an open-source tool that provides a UI for a distributed tracing system, which is useful for root cause analysis and for determining what causes poor performance. Distributed tracing allows you to view an entire chain of calls, which might originate with a user request and traverse dozens of microservices.
      • Get the full picture of your microservice architecture with Kiali. Kiali provides a diagram that shows the services within a service mesh and how they are connected, including the traffic rates and latencies between them. You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.
      • Gain insights from time series analytics with Grafana dashboards. Grafana is an analytics platform that allows you to query, visualize, alert on and understand the data gathered by Prometheus.
      • Write custom queries for time series data with the Prometheus UI. Prometheus is a systems monitoring and alerting toolkit. Prometheus scrapes data from your cluster, which is then used by Grafana. A Prometheus UI is also integrated into Rancher, and lets you write custom queries for time series data and see the results in the UI.

      Istio needs to be set up by a Rancher administrator or cluster administrator before it can be used in a project.

      Prerequisites

      Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

      Setup Guide

      Refer to the setup guide for instructions on how to set up Istio and use it in a project.

      Disabling Istio

      To remove Istio components from a cluster, namespace, or workload, refer to the section on disabling Istio.

      Accessing Visualizations

      By default, only cluster owners have access to Jaeger and Kiali. For instructions on how to allow project members to access them, see this section.

      After Istio is set up in a cluster, Grafana, Prometheus, Jaeger, and Kiali are available in the Rancher UI.

      Your access to the visualizations depend on your role. Grafana and Prometheus are only available for cluster owners. The Kiali and Jaeger UIs are available only to cluster owners by default, but cluster owners can allow project members to access them by editing the Istio settings. When you go to your project and click Resources > Istio, you can go to each UI for Kiali, Jaeger, Grafana, and Prometheus by clicking their icons in the top right corner of the page.

      To see the visualizations, go to the cluster where Istio is set up and click Tools > Istio. You should see links to each UI at the top of the page.

      You can also get to the visualization tools from the project view.

      Viewing the Kiali Traffic Graph

      1. From the project view in Rancher, click Resources > Istio.
      2. If you are a cluster owner, you can go to the Traffic Graph tab. This tab has the Kiali network visualization integrated into the UI.

      Viewing Traffic Metrics

      Istio’s monitoring features provide visibility into the performance of all your services.

      1. From the project view in Rancher, click Resources > Istio.
      2. Go to the Traffic Metrics tab. After traffic is generated in your cluster, you should be able to see metrics for Success Rate, Request Volume, 4xx Response Count, Project 5xx Response Count and Request Duration. Cluster owners can see all of the metrics, while project members can see a subset of the metrics.

      Architecture

      Istio installs a service mesh that uses Envoy sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.

      Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.

      Enabling Istio in Rancher enables monitoring in the cluster, and enables Istio in all new namespaces that are created in a cluster. You need to manually enable Istio in preexisting namespaces.

      When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.

      For more information on the Istio sidecar, refer to the Istio docs.

      Two Ingresses​

      By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. To allow Istio to receive external traffic, you need to enable the Istio ingress gateway for the cluster. The result is that your cluster will have two ingresses.

      In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/kubernetes-cluster-setup.html b/v2.0-v2.4/pages-for-subheaders/kubernetes-cluster-setup.html index 72aaca3f308..52e8964beca 100644 --- a/v2.0-v2.4/pages-for-subheaders/kubernetes-cluster-setup.html +++ b/v2.0-v2.4/pages-for-subheaders/kubernetes-cluster-setup.html @@ -5,13 +5,13 @@ Don't have a Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
      Version: v2.0-v2.4

      Don't have a Kubernetes cluster? Try one of these tutorials.

      This section contains information on how to install a Kubernetes cluster that the Rancher server can be installed on.

      In Rancher before v2.4, the Rancher server needed to run on an RKE Kubernetes cluster.

      In Rancher v2.4.x, Rancher needs to run on either an RKE Kubernetes cluster or a K3s Kubernetes cluster.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html b/v2.0-v2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html index 87b23286d61..0d3f379d809 100644 --- a/v2.0-v2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html +++ b/v2.0-v2.4/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html @@ -5,13 +5,13 @@ Setting up Kubernetes Clusters in Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Setting up Kubernetes Clusters in Rancher

      Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.

      This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

      For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the architecture page.

      The following table summarizes the options and settings available for each cluster type:

      ActionRancher launched Kubernetes ClustersHosted Kubernetes ClustersImported Clusters
      Using kubectl and a kubeconfig file to Access a Cluster✓✓✓
      Managing Cluster Members✓✓✓
      Editing and Upgrading Clusters✓✓*
      Managing Nodes✓✓✓
      Managing Persistent Volumes and Storage Classes✓✓✓
      Managing Projects, Namespaces and Workloads✓✓✓
      Using App Catalogs✓✓✓
      Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓
      Cloning Clusters✓✓
      Ability to rotate certificates✓
      Ability to back up your Kubernetes Clusters✓
      Ability to recover and restore etcd✓
      Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
      Configuring Pod Security Policies✓
      Running Security Scans✓
      Authorized Cluster Endpoint✓

      * Cluster configuration options can't be edited for imported clusters, except for K3s clusters.

      Setting up Clusters in a Hosted Kubernetes Provider

      In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

      If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

      For more information, refer to the section on hosted Kubernetes clusters.

      Launching Kubernetes with Rancher

      Rancher uses the Rancher Kubernetes Engine (RKE) as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer.

      In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform.

      These nodes can be dynamically provisioned through Rancher's UI, which calls Docker Machine to launch nodes on various cloud providers.

      If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it.

      For more information, refer to the section on RKE clusters.

      Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider​

      Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

      Using Rancher, you can create pools of nodes based on a node template. This template defines the parameters used to launch nodes in your cloud providers.

      One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration.

      The cloud providers available for creating a node template are decided based on the node drivers active in the Rancher UI.

      For more information, refer to the section on nodes hosted by an infrastructure provider

      Launching Kubernetes on Existing Custom Nodes​

      When setting up this type of cluster, Rancher installs Kubernetes on existing custom nodes, which creates a custom cluster.

      You can bring any nodes you want to Rancher and use them to create a cluster.

      These nodes include on-prem bare metal servers, cloud-hosted virtual machines, or on-prem virtual machines.

      Importing Existing Clusters

      Available from Rancher v2.0.x-v2.4.x

      In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

      Note that Rancher does not automate the provisioning, scaling, or upgrade of imported clusters. Other Rancher features, including management of cluster, role-based access control, policy, and workloads, are available for imported clusters.

      For all imported Kubernetes clusters except for K3s clusters, the configuration of an imported cluster still has to be edited outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters.

      In Rancher v2.4, it became possible to import a K3s cluster and upgrade Kubernetes by editing the cluster in the Rancher UI.

      For more information, refer to the section on importing existing clusters.

      Importing and Editing K3s Clusters​

      Available as of Rancher v2.4.0

      K3s is a lightweight, fully compliant Kubernetes distribution. K3s Kubernetes clusters can now be imported into Rancher.

      When a K3s cluster is imported, Rancher will recognize it as K3s, and the Rancher UI will expose the following features in addition to the functionality for other imported clusters:

      • The ability to upgrade the K3s version
      • The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster.

      For more information, refer to the section on imported K3s clusters.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/kubernetes-components.html b/v2.0-v2.4/pages-for-subheaders/kubernetes-components.html index 9e136b279bb..120fbf15f89 100644 --- a/v2.0-v2.4/pages-for-subheaders/kubernetes-components.html +++ b/v2.0-v2.4/pages-for-subheaders/kubernetes-components.html @@ -5,13 +5,13 @@ Kubernetes Components | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Components

      The commands and steps listed in this section apply to the core Kubernetes components on Rancher Launched Kubernetes clusters.

      This section includes troubleshooting tips in the following categories:

      Kubernetes Component Diagram

      Cluster diagram

      Lines show the traffic flow between components. Colors are used purely for visual aid
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/kubernetes-resources-setup.html b/v2.0-v2.4/pages-for-subheaders/kubernetes-resources-setup.html index cf03341f85e..d47165999b9 100644 --- a/v2.0-v2.4/pages-for-subheaders/kubernetes-resources-setup.html +++ b/v2.0-v2.4/pages-for-subheaders/kubernetes-resources-setup.html @@ -5,13 +5,13 @@ Kubernetes Resources | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Resources

      Workloads​

      Deploy applications to your cluster nodes using workloads, which are objects that contain pods that run your apps, along with metadata that set rules for the deployment's behavior. Workloads can be deployed within the scope of the entire clusters or within a namespace.

      When deploying a workload, you can deploy from any image. There are a variety of workload types to choose from which determine how your application should run.

      Following a workload deployment, you can continue working with it. You can:

      • Upgrade the workload to a newer version of the application it's running.
      • Roll back a workload to a previous version, if an issue occurs during upgrade.
      • Add a sidecar, which is a workload that supports a primary workload.

      Load Balancing and Ingress​

      Load Balancers​

      After you launch an application, it's only available within the cluster. It can't be reached externally.

      If you want your applications to be externally accessible, you must add a load balancer to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

      Rancher supports two types of load balancers:

      For more information, see load balancers.

      Ingress​

      Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive. You can get around this issue by using an ingress.

      Ingress is a set of rules that act as a load balancer. Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster program the load balancer to direct the request to the correct service based on service subdomains or path rules that you've configured.

      For more information, see Ingress.

      When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

      For more information, see Global DNS.

      Service Discovery​

      After you expose your cluster to external requests using a load balancer and/or ingress, it's only available by IP address. To create a resolveable hostname, you must create a service record, which is a record that maps an IP address, external hostname, DNS record alias, workload(s), or labelled pods to a specific hostname.

      For more information, see Service Discovery.

      Pipelines​

      After your project has been configured to a version control provider, you can add the repositories and start configuring a pipeline for each repository.

      For more information, see Pipelines.

      Applications​

      Besides launching individual components of an application, you can use the Rancher catalog to start launching applications, which are Helm charts.

      For more information, see Applications in a Project.

      Kubernetes Resources​

      Within the context of a Rancher project or namespace, resources are files and data that support operation of your pods. Within Rancher, certificates, registries, and secrets are all considered resources. However, Kubernetes classifies resources as different types of secrets. Therefore, within a single project or namespace, individual resources must have unique names to avoid conflicts. Although resources are primarily used to carry sensitive information, they have other uses as well.

      Resources include:

      • Certificates: Files used to encrypt/decrypt data entering or leaving the cluster.
      • ConfigMaps: Files that store general configuration information, such as a group of config files.
      • Secrets: Files that store sensitive data like passwords, tokens, or keys.
      • Registries: Files that carry credentials used to authenticate with private registries.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/launch-kubernetes-with-rancher.html b/v2.0-v2.4/pages-for-subheaders/launch-kubernetes-with-rancher.html index 78f85cffcdd..788a86d1489 100644 --- a/v2.0-v2.4/pages-for-subheaders/launch-kubernetes-with-rancher.html +++ b/v2.0-v2.4/pages-for-subheaders/launch-kubernetes-with-rancher.html @@ -5,13 +5,13 @@ Launching Kubernetes with Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Launching Kubernetes with Rancher

      You can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses Rancher Kubernetes Engine (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including:

      • Bare-metal servers
      • On-premise virtual machines
      • Virtual machines hosted by an infrastructure provider

      Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them.

      RKE clusters include clusters that Rancher launched on Windows nodes or other existing custom nodes, as well as clusters that Rancher launched with new nodes on Azure, Digital Ocean, EC2, or vSphere.

      Requirements​

      If you use RKE to set up a cluster, your nodes must meet the requirements for nodes in downstream user clusters.

      Launching Kubernetes on New Nodes in an Infrastructure Provider​

      Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your cloud providers.

      One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

      For more information, refer to the section on launching Kubernetes on new nodes.

      Launching Kubernetes on Existing Custom Nodes​

      In this scenario, you want to install Kubernetes on bare-metal servers, on-prem virtual machines, or virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine.

      If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

      For more information, refer to the section on custom nodes.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/load-balancer-and-ingress-controller.html b/v2.0-v2.4/pages-for-subheaders/load-balancer-and-ingress-controller.html index f300049ee18..f22bc23db94 100644 --- a/v2.0-v2.4/pages-for-subheaders/load-balancer-and-ingress-controller.html +++ b/v2.0-v2.4/pages-for-subheaders/load-balancer-and-ingress-controller.html @@ -5,13 +5,13 @@ Set Up Load Balancer and Ingress Controller within Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Set Up Load Balancer and Ingress Controller within Rancher

      Within Rancher, you can set up load balancers and ingress controllers to redirect service requests.

      Load Balancers​

      After you launch an application, the app is only available within the cluster. It can't be reached from outside the cluster.

      If you want your applications to be externally accessible, you must add a load balancer or ingress to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

      Rancher supports two types of load balancers:

      For more information, see load balancers.

      Load Balancer Limitations​

      Load Balancers have a couple of limitations you should be aware of:

      • Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive.

      • If you want to use a load balancer with a Hosted Kubernetes cluster (i.e., clusters hosted in GKE, EKS, or AKS), the load balancer must be running within that cloud provider's infrastructure. Please review the compatibility tables regarding support for load balancers based on how you've provisioned your clusters:

      - [Support for Layer-4 Load Balancing](/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing#support-for-layer-4-load-balancing)

      - [Support for Layer-7 Load Balancing](/v2.0-v2.4/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing#support-for-layer-7-load-balancing)

      Ingress​

      As mentioned in the limitations above, the disadvantages of using a load balancer are:

      • Load Balancers can only handle one IP address per service.
      • If you run multiple services in your cluster, you must have a load balancer for each service.
      • It can be expensive to have a load balancer for every service.

      In contrast, when an ingress is used as the entrypoint into a cluster, the ingress can route traffic to multiple services with greater flexibility. It can map multiple HTTP requests to services without individual IP addresses for each service.

      Therefore, it is useful to have an ingress if you want multiple services to be exposed with the same IP address, the same Layer 7 protocol, or the same privileged node-ports: 80 and 443.

      Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster direct the request to the correct service based on service subdomains or path rules that you've configured.

      Each Kubernetes Ingress resource corresponds roughly to a file in /etc/nginx/sites-available/ containing a server{} configuration block, where requests for specific files and folders are configured.

      Your ingress, which creates a port of entry to your cluster similar to a load balancer, can reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launched clusters are powered by Nginx.

      Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more.

      Using Rancher in a High Availability Configuration?

      Refrain from adding an Ingress to the local cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for all clusters managed by Rancher, including the local cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher.

      • For more information on how to set up ingress in Rancher, see Ingress.
      • For complete information about ingress and ingress controllers, see the Kubernetes Ingress Documentation
      • When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry, see Global DNS.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/manage-clusters.html b/v2.0-v2.4/pages-for-subheaders/manage-clusters.html index df615250a52..4f91696bc0a 100644 --- a/v2.0-v2.4/pages-for-subheaders/manage-clusters.html +++ b/v2.0-v2.4/pages-for-subheaders/manage-clusters.html @@ -5,13 +5,13 @@ Cluster Administration | Rancher Manager - +
      Version: v2.0-v2.4

      Cluster Administration

      After you provision a cluster in Rancher, you can begin using powerful Kubernetes features to deploy and scale your containerized applications in development, testing, or production environments.

      This page covers the following topics:

      This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

      Switching between Clusters​

      To switch between clusters, use the drop-down available in the navigation bar.

      Alternatively, you can switch between projects and clusters directly in the navigation bar. Open the Global view and select Clusters from the main menu. Then select the name of the cluster you want to open.

      Managing Clusters in Rancher​

      After clusters have been provisioned into Rancher, cluster owners will need to manage these clusters. There are many different options of how to manage your cluster.

      ActionRancher launched Kubernetes ClustersHosted Kubernetes ClustersImported Clusters
      Using kubectl and a kubeconfig file to Access a Cluster✓✓✓
      Managing Cluster Members✓✓✓
      Editing and Upgrading Clusters✓✓*
      Managing Nodes✓✓✓
      Managing Persistent Volumes and Storage Classes✓✓✓
      Managing Projects, Namespaces and Workloads✓✓✓
      Using App Catalogs✓✓✓
      Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓
      Cloning Clusters✓✓
      Ability to rotate certificates✓
      Ability to back up your Kubernetes Clusters✓
      Ability to recover and restore etcd✓
      Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
      Configuring Pod Security Policies✓
      Running Security Scans✓
      Authorized Cluster Endpoint✓

      * Cluster configuration options can't be edited for imported clusters, except for K3s clusters.

      Configuring Tools​

      Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories:

      • Alerts
      • Notifiers
      • Logging
      • Monitoring
      • Istio Service Mesh
      • OPA Gatekeeper

      For more information, see Tools

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/manage-persistent-storage.html b/v2.0-v2.4/pages-for-subheaders/manage-persistent-storage.html index 8087be88fcd..666255596c0 100644 --- a/v2.0-v2.4/pages-for-subheaders/manage-persistent-storage.html +++ b/v2.0-v2.4/pages-for-subheaders/manage-persistent-storage.html @@ -5,13 +5,13 @@ Manage Persistent Storage | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/manage-project-resource-quotas.html b/v2.0-v2.4/pages-for-subheaders/manage-project-resource-quotas.html index f106d9d9685..c91cfd61c68 100644 --- a/v2.0-v2.4/pages-for-subheaders/manage-project-resource-quotas.html +++ b/v2.0-v2.4/pages-for-subheaders/manage-project-resource-quotas.html @@ -5,13 +5,13 @@ Project Resource Quotas | Rancher Manager - +
      Version: v2.0-v2.4

      Project Resource Quotas

      Available as of v2.1.0

      In situations where several teams share a cluster, one team may overconsume the resources available: CPU, memory, storage, services, Kubernetes objects like pods or secrets, and so on. To prevent this overconsumption, you can apply a resource quota, which is a Rancher feature that limits the resources available to a project or namespace.

      This page is a how-to guide for creating resource quotas in existing projects.

      Resource quotas can also be set when a new project is created. For details, refer to the section on creating new projects.

      Resource quotas in Rancher include the same functionality as the native version of Kubernetes. In Rancher, resource quotas have been extended so that you can apply them to projects. For details on how resource quotas work with projects in Rancher, refer to this page.

      Applying Resource Quotas to Existing Projects​

      Available as of v2.0.1

      Edit resource quotas when:

      • You want to limit the resources that a project and its namespaces can use.
      • You want to scale the resources available to a project up or down when a research quota is already in effect.

      1. From the Global view, open the cluster containing the project to which you want to apply a resource quota.

      2. From the main menu, select Projects/Namespaces.

      3. Find the project that you want to add a resource quota to. From that project, select ⋮ > Edit.

      4. Expand Resource Quotas and click Add Quota. Alternatively, you can edit existing quotas.

      5. Select a Resource Type. For more information on types, see the quota type reference.

      6. Enter values for the Project Limit and the Namespace Default Limit.

        FieldDescription
        Project LimitThe overall resource limit for the project.
        Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit.

      7. Optional: Add more quotas.

      8. Click Create.

      Result: The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/manage-projects.html b/v2.0-v2.4/pages-for-subheaders/manage-projects.html index fa5d757cc71..3c15771ff5e 100644 --- a/v2.0-v2.4/pages-for-subheaders/manage-projects.html +++ b/v2.0-v2.4/pages-for-subheaders/manage-projects.html @@ -5,13 +5,13 @@ Project Administration | Rancher Manager - +
      Version: v2.0-v2.4

      Project Administration

      Projects are objects introduced in Rancher that help organize namespaces in your Kubernetes cluster. You can use projects to create multi-tenant clusters, which allows a group of users to share the same underlying resources without interacting with each other's applications.

      In terms of hierarchy:

      • Clusters contain projects
      • Projects contain namespaces

      Within Rancher, projects allow you to manage multiple namespaces as a single entity. In native Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace!

      Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each individual namespace.

      You can use projects to perform actions like:

      Authorization​

      Non-administrative users are only authorized for project access after an administrator, cluster owner or member, or project owner adds them to the project's Members tab.

      Whoever creates the project automatically becomes a project owner.

      Switching between Projects​

      To switch between projects, use the drop-down available in the navigation bar. Alternatively, you can switch between projects directly in the navigation bar.

      1. From the Global view, navigate to the project that you want to configure.

      2. Select Projects/Namespaces from the navigation bar.

      3. Select the link for the project that you want to open.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/manage-role-based-access-control-rbac.html b/v2.0-v2.4/pages-for-subheaders/manage-role-based-access-control-rbac.html index 1f8f8eeea79..d74a180957f 100644 --- a/v2.0-v2.4/pages-for-subheaders/manage-role-based-access-control-rbac.html +++ b/v2.0-v2.4/pages-for-subheaders/manage-role-based-access-control-rbac.html @@ -5,13 +5,13 @@ Role-Based Access Control (RBAC) | Rancher Manager - +
      Version: v2.0-v2.4

      Role-Based Access Control (RBAC)

      Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. As mentioned in Authentication, users can either be local or external.

      After you configure external authentication, the users that display on the Users page changes.

      • If you are logged in as a local user, only local users display.

      • If you are logged in as an external user, both external and local users display.

      Users and Roles​

      Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by global permissions, and cluster and project roles.

      • Global Permissions:

        Define user authorization outside the scope of any particular cluster.

      • Cluster and Project Roles:

        Define user authorization inside the specific cluster or project where they are assigned the role.

      Both global permissions and cluster and project roles are implemented on top of Kubernetes RBAC. Therefore, enforcement of permissions and roles is performed by Kubernetes.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/migrate-from-v1.6-v2.x.html b/v2.0-v2.4/pages-for-subheaders/migrate-from-v1.6-v2.x.html index 089c71469ab..fb114c10bff 100644 --- a/v2.0-v2.4/pages-for-subheaders/migrate-from-v1.6-v2.x.html +++ b/v2.0-v2.4/pages-for-subheaders/migrate-from-v1.6-v2.x.html @@ -5,13 +5,13 @@ Migrating from v1.6 to v2.x | Rancher Manager - +
      Version: v2.0-v2.4

      Migrating from v1.6 to v2.x

      Rancher v2.x has been rearchitected and rewritten with the goal of providing a complete management solution for Kubernetes and Docker. Due to these extensive changes, there is no direct upgrade path from v1.6 to v2.x, but rather a migration of your v1.6 services into v2.x as Kubernetes workloads. In v1.6, the most common orchestration used was Rancher's own engine called Cattle. The following guide explains and educates our Cattle users on running workloads in a Kubernetes environment.

      Video​

      This video demonstrates a complete walk through of migration from Rancher v1.6 to v2.x.

      Migration Plan​

      Want to more about Kubernetes before getting started? Read our Kubernetes Introduction.

      Migration Example Files​

      Throughout this migration guide, we will reference several example services from Rancher v1.6 that we're migrating to v2.x. These services are:

      • A service named web, which runs Let's Chat, a self-hosted chat for small teams.
      • A service named database, which runs Mongo DB, an open source document database.
      • A service named webLB, which runs HAProxy, an open source load balancer used in Rancher v1.6.

      During migration, we'll export these services from Rancher v1.6. The export generates a unique directory for each Rancher v1.6 environment and stack, and two files are output into each stack's directory:

      • docker-compose.yml

        A file that contains standard Docker directives for each service in your stack. We'll be converting these files to Kubernetes manifests that can be read by Rancher v2.x.

      • rancher-compose.yml

        A file for Rancher-specific functionality such as health checks and load balancers. These files cannot be read by Rancher v2.x, so don't worry about their contents—we're discarding them and recreating them using the v2.x UI.

      Next: Get Started​

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/new-user-guides.html b/v2.0-v2.4/pages-for-subheaders/new-user-guides.html index fc886fcd8bb..88cc0ab4075 100644 --- a/v2.0-v2.4/pages-for-subheaders/new-user-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/new-user-guides.html @@ -5,13 +5,13 @@ New User Guides | Rancher Manager - +
      Version: v2.0-v2.4

      New User Guides

      New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

      The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

      The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/node-template-configuration.html b/v2.0-v2.4/pages-for-subheaders/node-template-configuration.html index a3ce7b9e543..e5e3d930456 100644 --- a/v2.0-v2.4/pages-for-subheaders/node-template-configuration.html +++ b/v2.0-v2.4/pages-for-subheaders/node-template-configuration.html @@ -5,13 +5,13 @@ Node Template Configuration | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/other-cloud-providers.html b/v2.0-v2.4/pages-for-subheaders/other-cloud-providers.html index 7398e9c68bc..e707218ceb8 100644 --- a/v2.0-v2.4/pages-for-subheaders/other-cloud-providers.html +++ b/v2.0-v2.4/pages-for-subheaders/other-cloud-providers.html @@ -5,13 +5,13 @@ Other Cloud Providers | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/other-installation-methods.html b/v2.0-v2.4/pages-for-subheaders/other-installation-methods.html index 67fba9f306a..ca2ef4b7cf7 100644 --- a/v2.0-v2.4/pages-for-subheaders/other-installation-methods.html +++ b/v2.0-v2.4/pages-for-subheaders/other-installation-methods.html @@ -5,13 +5,13 @@ Other Installation Methods | Rancher Manager - +
      Version: v2.0-v2.4

      Other Installation Methods

      Air Gapped Installations​

      Follow these steps to install the Rancher server in an air gapped environment.

      An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

      Docker Installations​

      The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

      The Docker installation is for development and testing environments only.

      Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

      There is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/other-troubleshooting-tips.html b/v2.0-v2.4/pages-for-subheaders/other-troubleshooting-tips.html index 17037fd6448..fe7f347e54a 100644 --- a/v2.0-v2.4/pages-for-subheaders/other-troubleshooting-tips.html +++ b/v2.0-v2.4/pages-for-subheaders/other-troubleshooting-tips.html @@ -5,13 +5,13 @@ Other Troubleshooting Tips | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/pipelines.html b/v2.0-v2.4/pages-for-subheaders/pipelines.html index 92c0bba3069..f47ca67efb7 100644 --- a/v2.0-v2.4/pages-for-subheaders/pipelines.html +++ b/v2.0-v2.4/pages-for-subheaders/pipelines.html @@ -5,14 +5,14 @@ Pipelines | Rancher Manager - +
      Version: v2.0-v2.4

      Pipelines

      Rancher's pipeline provides a simple CI/CD experience. Use it to automatically checkout code, run builds or scripts, publish Docker images or catalog applications, and deploy the updated software to users.

      Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

      After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

      • Build your application from code to image.
      • Validate your builds.
      • Deploy your build images to your cluster.
      • Run unit tests.
      • Run regression tests.

      Notes:

      • Pipelines improved in Rancher v2.1. Therefore, if you configured pipelines while using v2.0.x, you'll have to reconfigure them after upgrading to v2.1.
      • Still using v2.0.x? See the pipeline documentation for previous versions.
      • Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses.

      Concepts​

      For an explanation of concepts and terminology used in this section, refer to this page.

      How Pipelines Work​

      After enabling the ability to use pipelines in a project, you can configure multiple pipelines in each project. Each pipeline is unique and can be configured independently.

      A pipeline is configured off of a group of files that are checked into source code repositories. Users can configure their pipelines either through the Rancher UI or by adding a .rancher-pipeline.yml into the repository.

      Before pipelines can be configured, you will need to configure authentication to your version control provider, e.g. GitHub, GitLab, Bitbucket. If you haven't configured a version control provider, you can always use Rancher's example repositories to view some common pipeline deployments.

      When you configure a pipeline in one of your projects, a namespace specifically for the pipeline is automatically created. The following components are deployed to it:

      • Jenkins:

        The pipeline's build engine. Because project users do not directly interact with Jenkins, it's managed and locked.

        Note: There is no option to use existing Jenkins deployments as the pipeline engine.

      • Docker Registry:

        Out-of-the-box, the default target for your build-publish step is an internal Docker Registry. However, you can make configurations to push to a remote registry instead. The internal Docker Registry is only accessible from cluster nodes and cannot be directly accessed by users. Images are not persisted beyond the lifetime of the pipeline and should only be used in pipeline runs. If you need to access your images outside of pipeline runs, please push to an external registry.

      • Minio:

        Minio storage is used to store the logs for pipeline executions.

        Note: The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in data persistency for pipeline components.

      Roles-based Access Control for Pipelines​

      If you can access a project, you can enable repositories to start building pipelines.

      Only administrators, cluster owners or members, or project owners can configure version control providers and manage global pipeline execution settings.

      Project members can only configure repositories and pipelines.

      Setting up Pipelines​

      To set up pipelines, you will need to do the following:

      1. Configure version control providers
      2. Configure repositories
      3. Configure the pipeline

      1. Configure Version Control Providers​

      Before you can start configuring a pipeline for your repository, you must configure and authorize a version control provider.

      ProviderAvailable as of
      GitHubv2.0.0
      GitLabv2.1.0
      Bitbucketv2.2.0

      Select your provider's tab below and follow the directions.

      1. From the Global view, navigate to the project that you want to configure pipelines.

      2. Select Tools > Pipelines in the navigation bar. In versions before v2.2.0, you can select Resources > Pipelines.

      3. Follow the directions displayed to Setup a Github application. Rancher redirects you to Github to setup an OAuth App in Github.

      4. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.

      5. If you're using GitHub for enterprise, select Use a private github enterprise installation. Enter the host address of your GitHub installation.

      6. Click Authenticate.

      Result: After the version control provider is authenticated, you will be automatically re-directed to start configuring which repositories you want start using with a pipeline.

      2. Configure Repositories​

      After the version control provider is authorized, you are automatically re-directed to start configuring which repositories that you want start using pipelines with. Even if someone else has set up the version control provider, you will see their repositories and can build a pipeline.

      1. From the Global view, navigate to the project that you want to configure pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Click on Configure Repositories.

      4. A list of repositories are displayed. If you are configuring repositories the first time, click on Authorize & Fetch Your Own Repositories to fetch your repository list.

      5. For each repository that you want to set up a pipeline, click on Enable.

      6. When you're done enabling all your repositories, click on Done.

      Results: You have a list of repositories that you can start configuring pipelines for.

      3. Configure the Pipeline​

      Now that repositories are added to your project, you can start configuring the pipeline by adding automated stages and steps. For your convenience, there are multiple built-in step types for dedicated tasks.

      1. From the Global view, navigate to the project that you want to configure pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Find the repository that you want to set up a pipeline for.

      4. Configure the pipeline through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml. Pipeline configuration is split into stages and steps. Stages must fully complete before moving onto the next stage, but steps in a stage run concurrently. For each stage, you can add different step types. Note: As you build out each step, there are different advanced options based on the step type. Advanced options include trigger rules, environment variables, and secrets. For more information on configuring the pipeline through the UI or the YAML file, refer to the pipeline configuration reference.

        • If you are going to use the UI, select the vertical ⋮ > Edit Config to configure the pipeline using the UI. After the pipeline is configured, you must view the YAML file and push it to the repository.
        • If you are going to use the YAML file, select the vertical ⋮ > View/Edit YAML to configure the pipeline. If you choose to use a YAML file, you need to push it to the repository after any changes in order for it to be updated in the repository. When editing the pipeline configuration, it takes a few moments for Rancher to check for an existing pipeline configuration.

      5. Select which branch to use from the list of branches.

      6. Available as of v2.2.0 Optional: Set up notifications.

      7. Set up the trigger rules for the pipeline.

      8. Enter a Timeout for the pipeline.

      9. When all the stages and steps are configured, click Done.

      Results: Your pipeline is now configured and ready to be run.

      Pipeline Configuration Reference​

      Refer to this page for details on how to configure a pipeline to:

      • Run a script
      • Build and publish images
      • Publish catalog templates
      • Deploy YAML
      • Deploy a catalog app

      The configuration reference also covers how to configure:

      • Notifications
      • Timeouts
      • The rules that trigger a pipeline
      • Environment variables
      • Secrets

      Running your Pipelines​

      Run your pipeline for the first time. From the project view in Rancher, go to Resources > Pipelines. (In versions before v2.3.0, go to the Pipelines tab.) Find your pipeline and select the vertical ⋮ > Run.

      During this initial run, your pipeline is tested, and the following pipeline components are deployed to your project as workloads in a new namespace dedicated to the pipeline:

      • docker-registry
      • jenkins
      • minio

      This process takes several minutes. When it completes, you can view each pipeline component from the project Workloads tab.

      Triggering a Pipeline​

      When a repository is enabled, a webhook is automatically set in the version control provider. By default, the pipeline is triggered by a push event to a repository, but you can modify the event(s) that trigger running the pipeline.

      Available Events:

      • Push: Whenever a commit is pushed to the branch in the repository, the pipeline is triggered.
      • Pull Request: Whenever a pull request is made to the repository, the pipeline is triggered.
      • Tag: When a tag is created in the repository, the pipeline is triggered.

      Note: This option doesn't exist for Rancher's example repositories.

      Modifying the Event Triggers for the Repository​

      1. From the Global view, navigate to the project that you want to modify the event trigger for the pipeline.

        1. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Find the repository that you want to modify the event triggers. Select the vertical ⋮ > Setting.

      4. Select which event triggers (Push, Pull Request or Tag) you want for the repository.

      5. Click Save.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/project-tools.html b/v2.0-v2.4/pages-for-subheaders/project-tools.html index 1b0a0e78396..e9b3c843baa 100644 --- a/v2.0-v2.4/pages-for-subheaders/project-tools.html +++ b/v2.0-v2.4/pages-for-subheaders/project-tools.html @@ -5,13 +5,13 @@ Tools for Logging, Monitoring, and More | Rancher Manager - +
      Version: v2.0-v2.4

      Tools for Logging, Monitoring, and More

      Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

      Notifiers

      Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

      Alerts

      Alerts are rules that trigger notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

      For details on project-level alerts, see this page.

      Logging

      Logging is helpful because it allows you to:

      • Capture and analyze the state of your cluster
      • Look for trends in your environment
      • Save your logs to a safe location outside of your cluster
      • Stay informed of events like a container crashing, a pod eviction, or a node dying
      • More easily debug and troubleshoot problems

      Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

      For details on setting up logging at the cluster level, refer to the logging section.

      For details on project-level logging, see this section.

      Monitoring

      Available as of v2.2.0

      Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. For details, refer to the monitoring section.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/provisioning-storage-examples.html b/v2.0-v2.4/pages-for-subheaders/provisioning-storage-examples.html index 43381e5ba7f..cd641637787 100644 --- a/v2.0-v2.4/pages-for-subheaders/provisioning-storage-examples.html +++ b/v2.0-v2.4/pages-for-subheaders/provisioning-storage-examples.html @@ -5,13 +5,13 @@ Provisioning Storage Examples | Rancher Manager - +
      Version: v2.0-v2.4

      Provisioning Storage Examples

      Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself.

      For your convenience, Rancher offers documentation on how to configure some of the popular storage methods:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/quick-start-guides.html b/v2.0-v2.4/pages-for-subheaders/quick-start-guides.html index 4d081942d9c..427af035729 100644 --- a/v2.0-v2.4/pages-for-subheaders/quick-start-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/quick-start-guides.html @@ -5,13 +5,13 @@ Rancher Deployment Quick Start Guides | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher Deployment Quick Start Guides

      Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

      Howdy buckaroos! Use this section of the docs to jump start your deployment and testing of Rancher 2.x! It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future.

      We have Quick Start Guides for:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-behind-an-http-proxy.html b/v2.0-v2.4/pages-for-subheaders/rancher-behind-an-http-proxy.html index 164c1cd5aa5..da1f47dced7 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-behind-an-http-proxy.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-behind-an-http-proxy.html @@ -5,13 +5,13 @@ Installing Rancher behind an HTTP Proxy | Rancher Manager - +
      Version: v2.0-v2.4

      Installing Rancher behind an HTTP Proxy

      In a lot of enterprise environments, servers or VMs running on premise do not have direct Internet access, but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to set up a highly available Rancher installation in such an environment.

      Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the Rancher docs.

      Installation Outline

      1. Set up infrastructure
      2. Set up a Kubernetes cluster
      3. Install Rancher
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-manager-architecture.html b/v2.0-v2.4/pages-for-subheaders/rancher-manager-architecture.html index a22c3a2bd89..099ed61cd43 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-manager-architecture.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-manager-architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
      Version: v2.0-v2.4

      Architecture

      This section focuses on the Rancher server and its components and how Rancher communicates with downstream Kubernetes clusters.

      For information on the different ways that Rancher can be installed, refer to the overview of installation options.

      For a list of main features of the Rancher API server, refer to the overview section.

      For guidance about setting up the underlying infrastructure for the Rancher server, refer to the architecture recommendations.

      note

      This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.html b/v2.0-v2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.html index e93fc88c011..b5d98f5964d 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-on-a-single-node-with-docker.html @@ -5,7 +5,7 @@ Installing Rancher on a Single Node Using Docker | Rancher Manager - + @@ -13,7 +13,7 @@
      Version: v2.0-v2.4

      Installing Rancher on a Single Node Using Docker

      Rancher can be installed by running a single Docker container.

      In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.

      Want to use an external load balancer? See Docker Install with an External Load Balancer instead.

      A Docker installation of Rancher is recommended only for development and testing purposes.

      For Rancher v2.0-v2.4, there is no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.

      Requirements for OS, Docker, Hardware, and Networking

      Make sure that your node fulfills the general installation requirements.

      1. Provision Linux Host

      Provision a single Linux host according to our Requirements to launch your Rancher server.

      2. Choose an SSL Option and Install Rancher

      For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

      Do you want to...

      Choose from the following options:

      Option A: Default Rancher-generated Self-signed Certificate​

      If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

      Log into your Linux host, and then run the minimum installation command below.

      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        rancher/rancher:latest

      Option B: Bring Your Own Certificate, Self-signed​

      In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.

      Prerequisites: Create a self-signed certificate using OpenSSL or another method of your choice.

      • The certificate files must be in PEM format.
      • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

      After creating your certificate, run the Docker command below to install Rancher. Use the -v flag and provide the path to your certificates to mount them in your container.

      PlaceholderDescription
      <CERT_DIRECTORY>The path to the directory containing your certificate files.
      <FULL_CHAIN.pem>The path to your full certificate chain.
      <PRIVATE_KEY.pem>The path to the private key for your certificate.
      <CA_CERTS.pem>The path to the certificate authority's certificate.
      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
        -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
        -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
        rancher/rancher:latest

      Option C: Bring Your Own Certificate, Signed by a Recognized CA​

      In production environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.

      Prerequisites:

      • The certificate files must be in PEM format.
      • In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

      After obtaining your certificate, run the Docker command below.

      • Use the -v flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
      • Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.
      PlaceholderDescription
      <CERT_DIRECTORY>The path to the directory containing your certificate files.
      <FULL_CHAIN.pem>The path to your full certificate chain.
      <PRIVATE_KEY.pem>The path to the private key for your certificate.
      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
        -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
        rancher/rancher:latest \
        --no-cacerts

      Option D: Let's Encrypt Certificate​

      Remember: Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

      For production environments, you also have the option of using Let's Encrypt certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, rancher.mydomain.com) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.

      Prerequisites:

      • Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
      • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
      • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.

      After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command.

      PlaceholderDescription
      <YOUR.DNS.NAME>Your domain address
      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        rancher/rancher:latest \
        --acme-domain <YOUR.DNS.NAME>

      Advanced Options​

      When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:

      • Custom CA Certificate
      • API Audit Log
      • TLS Settings
      • Air Gap
      • Persistent Data
      • Running rancher/rancher and rancher/rancher-agent on the Same Node

      Refer to this page for details.

      Troubleshooting​

      Refer to this page for frequently asked questions and troubleshooting tips.

      What's Next?​

      • Recommended: Review Single Node Backup and Restore. Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
      • Create a Kubernetes cluster: Provisioning Kubernetes Clusters.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-security.html b/v2.0-v2.4/pages-for-subheaders/rancher-security.html index 1ce92f98d75..3162b7032ee 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-security.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
      Version: v2.0-v2.4

      Security

      Security policy

      Rancher Labs supports responsible disclosure, and endeavours to resolve all issues in a reasonable time frame.

      Reporting process

      Please submit possible security issues by emailing security@rancher.com

      Announcements

      Subscribe to the Rancher announcements forum for release updates.

      Security is at the heart of all Rancher features. From integrating with all the popular authentication tools and services, to an enterprise grade RBAC capability, Rancher makes your Kubernetes clusters even more secure.

      On this page, we provide security-related documentation along with resources to help you secure your Rancher installation and your downstream Kubernetes clusters:

      Running a CIS Security Scan on a Kubernetes Cluster​

      Available as of v2.4.0

      Rancher leverages kube-bench to run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS (Center for Internet Security) Kubernetes Benchmark.

      The CIS Kubernetes Benchmark is a reference document that can be used to establish a secure configuration baseline for Kubernetes.

      The Center for Internet Security (CIS) is a 501(c)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace."

      CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.

      The Benchmark provides recommendations of two types: Scored and Not Scored. We run tests related to only Scored recommendations.

      When Rancher runs a CIS security scan on a cluster, it generates a report showing the results of each test, including a summary with the number of passed, skipped and failed tests. The report also includes remediation steps for any failed tests.

      For details, refer to the section on security scans.

      Rancher Hardening Guide​

      The Rancher Hardening Guide is based on controls and best practices found in the CIS Kubernetes Benchmark from the Center for Internet Security.

      The hardening guide provides prescriptive guidance for hardening a production installation of Rancher v2.1.x, v2.2.x and v.2.3.x. See Rancher's guides for Self Assessment of the CIS Kubernetes Benchmark for the full list of security controls.

      The hardening guides describe how to secure the nodes in your cluster, and it is recommended to follow a hardening guide before installing Kubernetes.

      Each version of the hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.4Rancher v2.4Benchmark v1.5Kubernetes v1.15
      Hardening Guide v2.3.5Rancher v2.3.5Benchmark v1.5Kubernetes v1.15
      Hardening Guide v2.3.3Rancher v2.3.3Benchmark v1.4.1Kubernetes v1.14, v1.15, and v1.16
      Hardening Guide v2.3Rancher v2.3.0-v2.3.2Benchmark v1.4.1Kubernetes v1.15
      Hardening Guide v2.2Rancher v2.2.xBenchmark v1.4.1 and 1.4.0Kubernetes v1.13
      Hardening Guide v2.1Rancher v2.1.xBenchmark v1.3.0Kubernetes v1.11

      The CIS Benchmark and Self-Assessment​

      The benchmark self-assessment is a companion to the Rancher security hardening guide. While the hardening guide shows you how to harden the cluster, the benchmark guide is meant to help you evaluate the level of security of the hardened cluster.

      Because Rancher and RKE install Kubernetes services as Docker containers, many of the control verification checks in the CIS Kubernetes Benchmark don't apply. This guide will walk through the various controls and provide updated example commands to audit compliance in Rancher created clusters. The original benchmark documents can be downloaded from the CIS website.

      Each version of Rancher's self-assessment guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

      Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
      Self Assessment Guide v2.4Rancher v2.4Hardening Guide v2.4Kubernetes v1.15Benchmark v1.5
      Self Assessment Guide v2.3.5Rancher v2.3.5Hardening Guide v2.3.5Kubernetes v1.15Benchmark v1.5
      Self Assessment Guide v2.3.3Rancher v2.3.3Hardening Guide v2.3.3Kubernetes v1.16Benchmark v1.4.1
      Self Assessment Guide v2.3Rancher v2.3.0-2.3.2Hardening Guide v2.3Kubernetes v1.15Benchmark v1.4.1
      Self Assessment Guide v2.2Rancher v2.2.xHardening Guide v2.2Kubernetes v1.13Benchmark v1.4.0 and v1.4.1
      Self Assessment Guide v2.1Rancher v2.1.xHardening Guide v2.1Kubernetes v1.11Benchmark 1.3.0

      Third-party Penetration Test Reports​

      Rancher periodically hires third parties to perform security audits and penetration tests of the Rancher 2.x software stack. The environments under test follow the Rancher provided hardening guides at the time of the testing. Results are posted when the third party has also verified fixes classified MEDIUM or above.

      Results:

      Rancher CVEs and Resolutions​

      Rancher is committed to informing the community of security issues in our products. For the list of CVEs (Common Vulnerabilities and Exposures) for issues we have resolved, refer to this page.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-server-configuration.html b/v2.0-v2.4/pages-for-subheaders/rancher-server-configuration.html index 1d1a3e3f01a..1d049772a07 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-server-configuration.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-server-configuration.html @@ -5,13 +5,13 @@ Rancher Server Configuration | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-v2.1-hardening-guides.html b/v2.0-v2.4/pages-for-subheaders/rancher-v2.1-hardening-guides.html index 5bc09aed375..e2aeb13a734 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-v2.1-hardening-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-v2.1-hardening-guides.html @@ -5,13 +5,13 @@ Rancher v2.1 | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher v2.1

      Self Assessment Guide​

      This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

      Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
      Self Assessment Guide v2.1Rancher v2.1.xHardening Guide v2.1Kubernetes 1.11Benchmark 1.3.0

      Hardening Guide​

      This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.1Rancher v2.1.xBenchmark v1.3.0Kubernetes 1.11
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-v2.2-hardening-guides.html b/v2.0-v2.4/pages-for-subheaders/rancher-v2.2-hardening-guides.html index 264c00f88c2..2ea06c78cdf 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-v2.2-hardening-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-v2.2-hardening-guides.html @@ -5,13 +5,13 @@ Rancher v2.2 | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher v2.2

      Self Assessment Guide​

      This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

      Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
      Self Assessment Guide v2.2Rancher v2.2.xHardening Guide v2.2Kubernetes 1.13Benchmark v1.4.0 and v1.4.1

      Hardening Guide​

      This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.2Rancher v2.2.xBenchmark v1.4.1, 1.4.0Kubernetes 1.13
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-v2.3-hardening-guides.html b/v2.0-v2.4/pages-for-subheaders/rancher-v2.3-hardening-guides.html index 40b3bb1f88a..4b59e577f5d 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-v2.3-hardening-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-v2.3-hardening-guides.html @@ -5,13 +5,13 @@ Rancher v2.3.x | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rancher-v2.4-hardening-guides.html b/v2.0-v2.4/pages-for-subheaders/rancher-v2.4-hardening-guides.html index 9aa2d833887..ef558491e04 100644 --- a/v2.0-v2.4/pages-for-subheaders/rancher-v2.4-hardening-guides.html +++ b/v2.0-v2.4/pages-for-subheaders/rancher-v2.4-hardening-guides.html @@ -5,13 +5,13 @@ Rancher v2.4 | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher v2.4

      Self Assessment Guide​

      This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

      Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
      Self Assessment Guide v2.4Rancher v2.4Hardening Guide v2.4Kubernetes v1.15Benchmark v1.5

      Hardening Guide​

      This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.4Rancher v2.4Benchmark v1.5Kubernetes 1.15
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/resources.html b/v2.0-v2.4/pages-for-subheaders/resources.html index b9ffe110c3a..c5841163570 100644 --- a/v2.0-v2.4/pages-for-subheaders/resources.html +++ b/v2.0-v2.4/pages-for-subheaders/resources.html @@ -5,13 +5,13 @@ Resources | Rancher Manager - +
      Version: v2.0-v2.4

      Resources

      Docker Installations​

      The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

      Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

      Air Gapped Installations​

      Follow these steps to install the Rancher server in an air gapped environment.

      An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

      Advanced Options​

      When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options:

      Advanced OptionAvailable as of
      Custom CA Certificatev2.0.0
      API Audit Logv2.0.0
      TLS Settingsv2.1.7
      etcd configurationv2.2.0
      Local System Charts for Air Gap Installationsv2.3.0
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/rke-add-on.html b/v2.0-v2.4/pages-for-subheaders/rke-add-on.html index 8d2f07819fb..3c3050f622a 100644 --- a/v2.0-v2.4/pages-for-subheaders/rke-add-on.html +++ b/v2.0-v2.4/pages-for-subheaders/rke-add-on.html @@ -5,13 +5,13 @@ RKE Add-On Install | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/set-up-cloud-providers.html b/v2.0-v2.4/pages-for-subheaders/set-up-cloud-providers.html index 35a9e522fec..aa1c433a768 100644 --- a/v2.0-v2.4/pages-for-subheaders/set-up-cloud-providers.html +++ b/v2.0-v2.4/pages-for-subheaders/set-up-cloud-providers.html @@ -5,13 +5,13 @@ Setting up Cloud Providers | Rancher Manager - +
      Version: v2.0-v2.4

      Setting up Cloud Providers

      A cloud provider is a module in Kubernetes that provides an interface for managing nodes, load balancers, and networking routes. For more information, refer to the official Kubernetes documentation on cloud providers.

      When a cloud provider is set up in Rancher, the Rancher server can automatically provision new nodes, load balancers or persistent storage devices when launching Kubernetes definitions, if the cloud provider you're using supports such automation.

      Your cluster will not provision correctly if you configure a cloud provider cluster of nodes that do not meet the prerequisites.

      By default, the Cloud Provider option is set to None.

      The following cloud providers can be enabled:

      • Amazon
      • Azure
      • GCE (Google Compute Engine)
      • vSphere

      Setting up the Amazon Cloud Provider​

      For details on enabling the Amazon cloud provider, refer to this page.

      Setting up the Azure Cloud Provider​

      For details on enabling the Azure cloud provider, refer to this page.

      Setting up the GCE Cloud Provider​

      For details on enabling the Google Compute Engine cloud provider, refer to this page.

      Setting up the vSphere Cloud Provider​

      For details on enabling the vSphere cloud provider, refer to this page.

      Setting up a Custom Cloud Provider​

      The Custom cloud provider is available if you want to configure any Kubernetes cloud provider.

      For the custom cloud provider option, you can refer to the RKE docs on how to edit the yaml file for your specific cloud provider. There are specific cloud providers that have more detailed configuration :

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html b/v2.0-v2.4/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html index f3b91176414..9b2ac479a85 100644 --- a/v2.0-v2.4/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html +++ b/v2.0-v2.4/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html @@ -5,13 +5,13 @@ Setting up Clusters from Hosted Kubernetes Providers | Rancher Manager - +
      Version: v2.0-v2.4

      Setting up Clusters from Hosted Kubernetes Providers

      In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

      If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

      In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-prem or in an infrastructure provider.

      Rancher supports the following Kubernetes providers:

      Kubernetes ProvidersAvailable as of
      Google GKE (Google Kubernetes Engine)v2.0.0
      Amazon EKS (Amazon Elastic Container Service for Kubernetes)v2.0.0
      Microsoft AKS (Azure Kubernetes Service)v2.0.0
      Alibaba ACK (Alibaba Cloud Container Service for Kubernetes)v2.2.0
      Tencent TKE (Tencent Kubernetes Engine)v2.2.0
      Huawei CCE (Huawei Cloud Container Engine)v2.2.0

      Hosted Kubernetes Provider Authentication​

      When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/single-node-rancher-in-docker.html b/v2.0-v2.4/pages-for-subheaders/single-node-rancher-in-docker.html index 5ceade9cfce..6072b342322 100644 --- a/v2.0-v2.4/pages-for-subheaders/single-node-rancher-in-docker.html +++ b/v2.0-v2.4/pages-for-subheaders/single-node-rancher-in-docker.html @@ -5,13 +5,13 @@ Single Node Rancher in Docker | Rancher Manager - +
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/upgrades.html b/v2.0-v2.4/pages-for-subheaders/upgrades.html index aacb6e75909..cdededb4958 100644 --- a/v2.0-v2.4/pages-for-subheaders/upgrades.html +++ b/v2.0-v2.4/pages-for-subheaders/upgrades.html @@ -5,14 +5,14 @@ Upgrades | Rancher Manager - +
      Version: v2.0-v2.4

      Upgrades

      The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.

      For the instructions to upgrade Rancher installed with Docker, refer to this page.

      To upgrade the components in your Kubernetes cluster, or the definition of the Kubernetes services or add-ons, refer to the upgrade documentation for RKE, the Rancher Kubernetes Engine.

      If you installed Rancher using the RKE Add-on yaml, follow the directions to migrate or upgrade.

      Prerequisites

      Access to kubeconfig​

      Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.

      If you installed Kubernetes with RKE, the config will have been created in the directory you ran rke up in.

      The kubeconfig can also be manually targeted for the intended cluster with the --kubeconfig tag (see: https://helm.sh/docs/helm/helm/)

      Review Known Issues​

      Review the known upgrade issues in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.

      A more complete list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

      Note that upgrades to or from any chart in the rancher-alpha repository aren't supported.

      Helm Version​

      The upgrade instructions assume you are using Helm 3.

      For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. The Helm 2 upgrade page hereprovides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

      For air gap installs: Populate private registry​

      -For air gap installs only, collect and populate images for the new Rancher server version. Follow the guide to populate your private registry with the images for the Rancher version that you want to upgrade to.

      For upgrades from v2.0-v2.2 with external TLS termination​

      If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to enable using forwarded host headers.

      For upgrades with cert-manager older than 0.8.0​

      Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019. Upgrade cert-manager to the latest version by following these instructions.

      Upgrade Outline

      Follow the steps to upgrade Rancher server:

      1. Back up Your Kubernetes Cluster that is Running Rancher Server

      Take a one-time snapshot of your Kubernetes cluster running Rancher server.

      You'll use the backup as a restoration point if something goes wrong during upgrade.

      2. Update the Helm chart repository

      1. Update your local helm repo cache.

        helm repo update

      2. Get the repository name that you used to install Rancher.

        For information about the repos and their differences, see Helm Chart Repositories.

        • Latest: Recommended for trying out the newest features
          helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
        • Stable: Recommended for production environments
          helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
        • Alpha: Experimental preview of upcoming releases.
          helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
          Note: Upgrades are not supported to, from, or between Alphas.
        helm repo list

        NAME                   URL
        stable                 https://charts.helm.sh/stable
        rancher-<CHART_REPO>     https://releases.rancher.com/server-charts/<CHART_REPO>

        Note: If you want to switch to a different Helm chart repository, please follow the steps on how to switch repositories. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.

      1. Fetch the latest chart to install Rancher from the Helm chart repository.

        This command will pull down the latest charts and save it in the current directory as a .tgz file.

        helm fetch rancher-<CHART_REPO>/rancher

        You can fetch the chart for the specific version you are upgrading to by adding in the --version= tag. For example:

        helm fetch rancher-<CHART_REPO>/rancher --version=v2.4.11

      3. Upgrade Rancher

      This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.

      Get the values, which were passed with --set, from the current Rancher Helm chart that is installed.

      helm get values rancher -n cattle-system

      hostname: rancher.my.org

      Note: There will be more values that are listed with this command. This is just an example of one of the values.

      If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher and cert-manager.

      Otherwise, follow Option A: Upgrading Rancher.

      Option A: Upgrading Rancher​

      Upgrade Rancher to the latest version with all your settings.

      Take all the values from the previous step and append them to the command using --set key=value:

      helm upgrade rancher rancher-<CHART_REPO>/rancher \
        --namespace cattle-system \
        --set hostname=rancher.my.org

      Note: The above is an example, there may be more values from the previous step that need to be appended.

      Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:

      helm get values rancher -n cattle-system -o yaml > values.yaml

      helm upgrade rancher rancher-<CHART_REPO>/rancher \
        --namespace cattle-system \
        -f values.yaml \
        --version=2.4.5

      Option B: Reinstalling Rancher and cert-manager​

      If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.

      1. Uninstall Rancher

        helm delete rancher -n cattle-system

      2. Uninstall and reinstall cert-manager according to the instructions on the Upgrading Cert-Manager page.

      3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using --set key=value. Note: There will be many more options from the step 1 that need to be appended.

        helm install rancher rancher-<CHART_REPO>/rancher \
        --namespace cattle-system \
        --set hostname=rancher.my.org

      4. Verify the Upgrade

      Log into Rancher to confirm that the upgrade succeeded.

      Having network issues following upgrade?

      See Restoring Cluster Networking.

      Known Upgrade Issues

      The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

      Upgrade ScenarioIssue
      Upgrading to v2.4.6 or v2.4.7These Rancher versions had an issue where the kms:ListKeys permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.
      Upgrading to v2.3.0+Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.
      Upgrading to v2.2.0-v2.2.xRancher introduced the system charts repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the system-charts repository locally and configure Rancher to use that repository. Please follow the instructions to configure Rancher system charts.
      Upgrading from v2.0.13 or earlierIf your cluster's certificates have expired, you will need to perform additional steps to rotate the certificates.
      Upgrading from v2.0.7 or earlierRancher introduced the system project, which is a project that's automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they're unassigned to prevent cluster networking issues.

      RKE Add-on Installs

      Important: RKE add-on install is only supported up to Rancher v2.0.8

      Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the Kubernetes Install.

      If you are currently using the RKE add-on install method, see Migrating from a RKE add-on install for details on how to move to using the helm chart.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/use-existing-nodes.html b/v2.0-v2.4/pages-for-subheaders/use-existing-nodes.html index c8dc77a4ee1..4e01f793601 100644 --- a/v2.0-v2.4/pages-for-subheaders/use-existing-nodes.html +++ b/v2.0-v2.4/pages-for-subheaders/use-existing-nodes.html @@ -5,13 +5,13 @@ Launching Kubernetes on Existing Custom Nodes | Rancher Manager - +
      Version: v2.0-v2.4

      Launching Kubernetes on Existing Custom Nodes

      When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to create a Kubernetes cluster in on-prem bare-metal servers, on-prem virtual machines, or in any node hosted by an infrastructure provider.

      To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to the requirements, which includes some hardware specifications and Docker. After you install Docker on each server, you willl also run the command provided in the Rancher UI on each server to turn each one into a Kubernetes node.

      This section describes how to set up a custom cluster.

      Creating a Cluster with Custom Nodes

      Want to use Windows hosts as Kubernetes workers?

      See Configuring Custom Clusters for Windows before you start.

      1. Provision a Linux Host​

      Begin creation of a custom cluster by provisioning a Linux host. Your host can be:

      • A cloud-host virtual machine (VM)
      • An on-prem VM
      • A bare-metal server

      If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

      Provision the host according to the installation requirements and the checklist for production-ready clusters.

      2. Create the Custom Cluster​

      1. From the Clusters page, click Add Cluster.

      2. Choose Custom.

      3. Enter a Cluster Name.

      4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

      5. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options.

        Using Windows nodes as Kubernetes workers?

      6. Click **Next**.

      7. From Node Role, choose the roles that you want filled by a cluster node.

        Notes:

        • Using Windows nodes as Kubernetes workers? See this section.
        • Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers).
      8. **Optional**: Click **[Show advanced options](admin-settings/agent-options/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.

      9. Copy the command displayed on screen to your clipboard.

      10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

        Note: Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed.

      11. When you finish running the command(s) on your Linux host(s), click Done.

      Result:

      Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

      You can access your cluster after its state is updated to Active.

      Active clusters are assigned two Projects:

      • Default, containing the default namespace
      • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

      3. Amazon Only: Tag Resources​

      If you have configured your cluster to use Amazon as Cloud Provider, tag your AWS resources with a cluster ID.

      Amazon Documentation: Tagging Your Amazon EC2 Resources

      Note: You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see Kubernetes Cloud Providers

      The following resources need to tagged with a ClusterID:

      • Nodes: All hosts added in Rancher.

      • Subnet: The subnet used for your cluster

      • Security Group: The security group used for your cluster.

        Note: Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer.

      The tag that should be used is:

      Key=kubernetes.io/cluster/<CLUSTERID>, Value=owned

      <CLUSTERID> can be any string you choose. However, the same string must be used on every resource you tag. Setting the tag value to owned informs the cluster that all resources tagged with the <CLUSTERID> are owned and managed by this cluster.

      If you share resources between clusters, you can change the tag to:

      Key=kubernetes.io/cluster/CLUSTERID, Value=shared

      Optional Next Steps

      After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

      • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
      • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html b/v2.0-v2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html index 72834a4262a..484c87508c8 100644 --- a/v2.0-v2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html +++ b/v2.0-v2.4/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html @@ -5,13 +5,13 @@ Launching Kubernetes on New Nodes in an Infrastructure Provider | Rancher Manager - +
      Version: v2.0-v2.4

      Launching Kubernetes on New Nodes in an Infrastructure Provider

      Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers.

      One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

      The available cloud providers to create a node template are decided based on active node drivers.

      Node Templates

      A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses Docker Machine to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher.

      After you create a node template in Rancher, it's saved so that you can use this template again to create node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile.

      Node Labels​

      You can add labels on each node template, so that any nodes created from the node template will automatically have these labels on them.

      Node Taints​

      Available as of Rancher v2.3.0

      You can add taints on each node template, so that any nodes created from the node template will automatically have these taints on them.

      Since taints can be added at a node template and node pool, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

      Administrator Control of Node Templates​

      Available as of v2.3.3

      Administrators can control all node templates. Admins can now maintain all the node templates within Rancher. When a node template owner is no longer using Rancher, the node templates created by them can be managed by administrators so the cluster can continue to be updated and maintained.

      To access all node templates, an administrator will need to do the following:

      1. In the Rancher UI, click the user profile icon in the upper right corner.
      2. Click Node Templates.

      Result: All node templates are listed and grouped by owner. The templates can be edited or cloned by clicking the ⋮.

      Node Pools

      Using Rancher, you can create pools of nodes based on a node template.

      A node template defines the configuration of a node, like what operating system to use, number of CPUs and amount of memory.

      The benefit of using a node pool is that if a node is destroyed or deleted, you can increase the number of live nodes to compensate for the node that was lost. The node pool helps you ensure that the count of the node pool is as expected.

      Each node pool must have one or more nodes roles assigned.

      Each node role (i.e. etcd, control plane, and worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.

      The recommended setup is to have:

      • a node pool with the etcd node role and a count of three
      • a node pool with the control plane node role and a count of at least two
      • a node pool with the worker node role and a count of at least two

      Node Pool Taints​

      Available as of Rancher v2.3.0

      If you haven't defined taints on your node template, you can add taints for each node pool. The benefit of adding taints at a node pool is beneficial over adding it at a node template is that you can swap out the node templates without worrying if the taint is on the node template.

      For each taint, they will automatically be added to any created node in the node pool. Therefore, if you add taints to a node pool that have existing nodes, the taints won't apply to existing nodes in the node pool, but any new node added into the node pool will get the taint.

      When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

      About Node Auto-replace​

      Available as of Rancher v2.3.0

      If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes.

      Important: Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

      Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the --node-monitor-period flag of the kube-controller). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool.

      Enabling Node Auto-replace​

      When you create the node pool, you can specify the amount of time in minutes that Rancher will wait to replace an unresponsive node.

      1. In the form for creating a cluster, go to the Node Pools section.
      2. Go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
      3. Fill out the rest of the form for creating a cluster.

      Result: Node auto-replace is enabled for the node pool.

      You can also enable node auto-replace after the cluster is created with the following steps:

      1. From the Global view, click the Clusters tab.
      2. Go to the cluster where you want to enable node auto-replace, click the vertical ⋮ (…), and click Edit.
      3. In the Node Pools section, go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
      4. Click Save.

      Result: Node auto-replace is enabled for the node pool.

      Disabling Node Auto-replace​

      You can disable node auto-replace from the Rancher UI with the following steps:

      1. From the Global view, click the Clusters tab.
      2. Go to the cluster where you want to enable node auto-replace, click the vertical ⋮ (…), and click Edit.
      3. In the Node Pools section, go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter 0.
      4. Click Save.

      Result: Node auto-replace is disabled for the node pool.

      Cloud Credentials

      Available as of v2.2.0

      Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits:

      • Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time.

      • After the cloud credential is created, it can be re-used to create additional node templates.

      • Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once.

      Note: As of v2.2.0, the default active node drivers and any node driver, that has fields marked as password, are required to use cloud credentials. If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it.

      After cloud credentials are created, the user can start managing the cloud credentials that they created.

      Node Drivers

      If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in node drivers and activate it, or you can add your own custom node driver.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/use-windows-clusters.html b/v2.0-v2.4/pages-for-subheaders/use-windows-clusters.html index c753e9e7557..9dc7c014d68 100644 --- a/v2.0-v2.4/pages-for-subheaders/use-windows-clusters.html +++ b/v2.0-v2.4/pages-for-subheaders/use-windows-clusters.html @@ -5,13 +5,13 @@ Launching Kubernetes on Windows Clusters | Rancher Manager - +
      Version: v2.0-v2.4

      Launching Kubernetes on Windows Clusters

      Available as of v2.3.0

      When provisioning a custom cluster using Rancher, Rancher uses RKE (the Rancher Kubernetes Engine) to install Kubernetes on your existing nodes.

      In a Windows cluster provisioned with Rancher, the cluster must contain both Linux and Windows nodes. The Kubernetes controlplane can only run on Linux nodes, and the Windows nodes can only have the worker role. Windows nodes can only be used for deploying workloads.

      Some other requirements for Windows clusters include:

      • You can only add Windows nodes to a cluster if Windows support is enabled when the cluster is created. Windows support cannot be enabled for existing clusters.
      • Kubernetes 1.15+ is required.
      • The Flannel network provider must be used.
      • Windows nodes must have 50 GB of disk space.

      For the full list of requirements, see this section.

      For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on supported functionality and limitations for using Kubernetes with Windows or the guide for scheduling Windows containers in Kubernetes.

      Requirements for Windows Clusters

      The general node requirements for networking, operating systems, and Docker are the same as the node requirements for a Rancher installation.

      OS and Docker Requirements​

      In order to add Windows worker nodes to a cluster, the node must be running one of the following Windows Server versions and the corresponding version of Docker Engine - Enterprise Edition (EE):

      • Nodes with Windows Server core version 1809 should use Docker EE-basic 18.09 or Docker EE-basic 19.03.
      • Nodes with Windows Server core version 1903 should use Docker EE-basic 19.03.

      Notes:

      • If you are using AWS, Rancher recommends Microsoft Windows Server 2019 Base with Containers as the Amazon Machine Image (AMI).
      • If you are using GCE, Rancher recommends Windows Server 2019 Datacenter for Containers as the OS image.

      Kubernetes Version​

      Kubernetes v1.15+ is required.

      Node Requirements​

      The hosts in the cluster need to have at least:

      • 2 core CPUs
      • 5 GB memory
      • 50 GB disk space

      Rancher will not provision the node if the node does not meet these requirements.

      Networking Requirements​

      Before provisioning a new cluster, be sure that you have already installed Rancher on a device that accepts inbound network traffic. This is required in order for the cluster nodes to communicate with Rancher. If you have not already installed Rancher, please refer to the installation documentation before proceeding with this guide.

      Rancher only supports Windows using Flannel as the network provider.

      There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.

      For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

      For VXLAN (Overlay) networking, the KB4489899 hotfix must be installed. Most cloud-hosted VMs already have this hotfix.

      If you are configuring DHCP options sets for an AWS virtual private cloud, note that in the domain-name option field, only one domain name can be specified. According to the DHCP options documentation:

      Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name.

      Architecture Requirements​

      The Kubernetes cluster management nodes (etcd and controlplane) must be run on Linux nodes.

      The worker nodes, which is where your workloads will be deployed on, will typically be Windows nodes, but there must be at least one worker node that is run on Linux in order to run the Rancher cluster agent, DNS, metrics server, and Ingress related containers.

      We recommend the minimum three-node architecture listed in the table below, but you can always add additional Linux and Windows workers to scale up your cluster for redundancy:

      NodeOperating SystemKubernetes Cluster Role(s)Purpose
      Node 1Linux (Ubuntu Server 18.04 recommended)Control plane, etcd, workerManage the Kubernetes cluster
      Node 2Linux (Ubuntu Server 18.04 recommended)WorkerSupport the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster
      Node 3Windows (Windows Server core version 1809 or above)WorkerRun your Windows containers

      Container Requirements​

      Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server core version 1809 or above. If you have existing containers built for an earlier Windows Server core version, they must be re-built on Windows Server core version 1809 or above.

      Cloud Provider Specific Requirements​

      If you set a Kubernetes cloud provider in your cluster, some additional steps are required. You might want to set a cloud provider if you want to want to leverage a cloud provider's capabilities, for example, to automatically provision storage, load balancers, or other infrastructure for your cluster. Refer to this page for details on how to configure a cloud provider cluster of nodes that meet the prerequisites.

      If you are using the GCE (Google Compute Engine) cloud provider, you must do the following:

      • Enable the GCE cloud provider in the cluster.yml by following these steps.
      • When provisioning the cluster in Rancher, choose Custom cloud provider as the cloud provider in the Rancher UI.

      Tutorial: How to Create a Cluster with Windows Support

      This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the recommended architecture.

      When you provision a cluster with Rancher on existing nodes, you will add nodes to the cluster by installing the Rancher agent on each one. When you create or edit your cluster from the Rancher UI, you will see a Customize Node Run Command that you can run on each server to add it to your cluster.

      To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below.

      1. Provision Hosts

      To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts.

      Your hosts can be:

      • Cloud-hosted VMs
      • VMs from virtualization clusters
      • Bare-metal servers

      You will provision three nodes:

      • One Linux node, which manages the Kubernetes control plane and stores your etcd
      • A second Linux node, which will be another worker node
      • The Windows node, which will run your Windows containers as a worker node
      NodeOperating System
      Node 1Linux (Ubuntu Server 18.04 recommended)
      Node 2Linux (Ubuntu Server 18.04 recommended)
      Node 3Windows (Windows Server core version 1809 or above required)

      If your nodes are hosted by a Cloud Provider and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see Selecting Cloud Providers.

      2. Create the Cluster on Existing Nodes

      The instructions for creating a Windows cluster on existing nodes are very similar to the general instructions for creating a custom cluster with some Windows-specific requirements.

      1. From the Global view, click on the Clusters tab and click Add Cluster.
      2. Click From existing nodes (Custom).
      3. Enter a name for your cluster in the Cluster Name text box.
      4. In the Kubernetes Version dropdown menu, select v1.15 or above.
      5. In the Network Provider field, select Flannel.
      6. In the Windows Support section, click Enable.
      7. Optional: After you enable Windows support, you will be able to choose the Flannel backend. There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.
      8. Click Next.

      Important: For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

      3. Add Nodes to the Cluster

      This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node.

      Add Linux Master Node​

      In this section, we fill out a form on the Rancher UI to get a custom command to install the Rancher agent on the Linux master node. Then we will copy the command and run it on our Linux master node to register the node in the cluster.

      The first node in your cluster should be a Linux host has both the Control Plane and etcd roles. At a minimum, both of these roles must be enabled for this node, and this node must be added to your cluster before you can add Windows hosts.

      1. In the Node Operating System section, click Linux.
      2. In the Node Role section, choose at least etcd and Control Plane. We recommend selecting all three.
      3. Optional: If you click Show advanced options, you can customize the settings for the Rancher agent and node labels.
      4. Copy the command displayed on the screen to your clipboard.
      5. SSH into your Linux host and run the command that you copied to your clipboard.
      6. When you are finished provisioning your Linux node(s), select Done.

      Result:

      Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

      You can access your cluster after its state is updated to Active.

      Active clusters are assigned two Projects:

      • Default, containing the default namespace
      • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

      It may take a few minutes for the node to be registered in your cluster.

      Add Linux Worker Node​

      In this section, we run a command to register the Linux worker node to the cluster.

      After the initial provisioning of your cluster, your cluster only has a single Linux host. Next, we add another Linux worker host, which will be used to support Rancher cluster agent, Metrics server, DNS and Ingress for your cluster.

      1. From the Global view, click Clusters.
      2. Go to the cluster that you created and click ⋮ > Edit.
      3. Scroll down to Node Operating System. Choose Linux.
      4. In the Customize Node Run Command section, go to the Node Options and select the Worker role.
      5. Copy the command displayed on screen to your clipboard.
      6. Log in to your Linux host using a remote Terminal connection. Run the command copied to your clipboard.
      7. From Rancher, click Save.

      Result: The Worker role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.

      Note: Taints on Linux Worker Nodes

      For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.

      Taint KeyTaint ValueTaint Effect
      cattle.io/oslinuxNoSchedule

      Add a Windows Worker Node​

      In this section, we run a command to register the Windows worker node to the cluster.

      You can add Windows hosts to the cluster by editing the cluster and choosing the Windows option.

      1. From the Global view, click Clusters.
      2. Go to the cluster that you created and click ⋮ > Edit.
      3. Scroll down to Node Operating System. Choose Windows. Note: You will see that the worker role is the only available role.
      4. Copy the command displayed on screen to your clipboard.
      5. Log in to your Windows host using your preferred tool, such as Microsoft Remote Desktop. Run the command copied to your clipboard in the Command Prompt (CMD).
      6. From Rancher, click Save.
      7. Optional: Repeat these instructions if you want to add more Windows nodes to your cluster.

      Result: The Worker role is installed on your Windows host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster. You now have a Windows Kubernetes cluster.

      Optional Next Steps​

      After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

      • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
      • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

      Configuration for Storage Classes in Azure

      If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster. For details, refer to this section.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/user-settings.html b/v2.0-v2.4/pages-for-subheaders/user-settings.html index 155c8256c8f..76768df9903 100644 --- a/v2.0-v2.4/pages-for-subheaders/user-settings.html +++ b/v2.0-v2.4/pages-for-subheaders/user-settings.html @@ -5,13 +5,13 @@ User Settings | Rancher Manager - +
      Version: v2.0-v2.4

      User Settings

      Within Rancher, each user has a number of settings associated with their login: personal preferences, API keys, etc. You can configure these settings by choosing from the User Settings menu. You can open this menu by clicking your avatar, located within the main menu.

      User Settings Menu

      The available user settings are:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/vsphere.html b/v2.0-v2.4/pages-for-subheaders/vsphere.html index fa6982900c3..b1f3c94404c 100644 --- a/v2.0-v2.4/pages-for-subheaders/vsphere.html +++ b/v2.0-v2.4/pages-for-subheaders/vsphere.html @@ -5,13 +5,13 @@ Creating a vSphere Cluster | Rancher Manager - +
      Version: v2.0-v2.4

      Creating a vSphere Cluster

      By using Rancher with vSphere, you can bring cloud operations on-premises.

      Rancher can provision nodes in vSphere and install Kubernetes on them. When creating a Kubernetes cluster in vSphere, Rancher first provisions the specified number of virtual machines by communicating with the vCenter API. Then it installs Kubernetes on top of them.

      A vSphere cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role.

      vSphere Enhancements in Rancher v2.3​

      The vSphere node templates have been updated, allowing you to bring cloud operations on-premises with the following enhancements:

      Self-healing Node Pools​

      Available as of v2.3.0

      One of the biggest advantages of provisioning vSphere nodes with Rancher is that it allows you to take advantage of Rancher's self-healing node pools, also called the node auto-replace feature, in your on-premises clusters. Self-healing node pools are designed to help you replace worker nodes for stateless applications. When Rancher provisions nodes from a node template, Rancher can automatically replace unreachable nodes.

      Important: It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

      Dynamically Populated Options for Instances and Scheduling​

      Available as of v2.3.3

      Node templates for vSphere have been updated so that when you create a node template with your vSphere credentials, the template is automatically populated with the same options for provisioning VMs that you have access to in the vSphere console.

      For the fields to be populated, your setup needs to fulfill the prerequisites.

      More Supported Operating Systems​

      In Rancher v2.3.3+, you can provision VMs with any operating system that supports cloud-init. Only YAML format is supported for the cloud config.

      In Rancher before v2.3.3, the vSphere node driver included in Rancher only supported the provisioning of VMs with RancherOS as the guest operating system.

      Video Walkthrough of v2.3.3 Node Template Features​

      In this YouTube video, we demonstrate how to set up a node template with the new features designed to help you bring cloud operations to on-premises clusters.

      Creating a vSphere Cluster​

      In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

      Provisioning Storage​

      For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

      Enabling the vSphere Cloud Provider​

      When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices.

      For details, refer to the section on enabling the vSphere cloud provider.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/pages-for-subheaders/workloads-and-pods.html b/v2.0-v2.4/pages-for-subheaders/workloads-and-pods.html index 95b8a1f9f23..2b761245196 100644 --- a/v2.0-v2.4/pages-for-subheaders/workloads-and-pods.html +++ b/v2.0-v2.4/pages-for-subheaders/workloads-and-pods.html @@ -5,14 +5,14 @@ Kubernetes Workloads and Pods | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Workloads and Pods

      You can build any complex containerized application in Kubernetes using two basic constructs: pods and workloads. Once you build an application, you can expose it for access either within the same cluster or on the Internet using a third construct: services.

      Pods​

      Pods are one or more containers that share network namespaces and storage volumes. Most pods have only one container. Therefore when we discuss pods, the term is often synonymous with containers. You scale pods the same way you scale containers—by having multiple instances of the same pod that implement a service. Usually pods get scaled and managed by the workload.

      Workloads​

      Workloads are objects that set deployment rules for pods. Based on these rules, Kubernetes performs the deployment and updates the workload with the current state of the application. Workloads let you define the rules for application scheduling, scaling, and upgrade.

      Workload Types​

      Kubernetes divides workloads into different types. The most popular types supported by Kubernetes are:

      • Deployments

        Deployments are best used for stateless applications (i.e., when you don't have to maintain the workload's state). Pods managed by deployment workloads are treated as independent and disposable. If a pod encounters disruption, Kubernetes removes it and then recreates it. An example application would be an Nginx web server.

      • StatefulSets

        StatefulSets, in contrast to deployments, are best used when your application needs to maintain its identity and store data. An application would be something like Zookeeper—an application that requires a database for storage.

      • DaemonSets

        Daemonsets ensures that every node in the cluster runs a copy of pod. For use cases where you're collecting logs or monitoring node performance, this daemon-like workload works best.

      • Jobs

        Jobs launch one or more pods and ensure that a specified number of them successfully terminate. Jobs are best used to run a finite task to completion as opposed to managing an ongoing desired application state.

      • CronJobs

        CronJobs are similar to jobs. CronJobs, however, runs to completion on a cron-based schedule.

      Services​

      In many use cases, a workload has to be either:

      • Accessed by other workloads in the cluster.
      • Exposed to the outside world.

      You can achieve these goals by creating a Service. Services are mapped to the underlying workload's pods using a selector/label approach (view the code samples). Rancher UI simplifies this mapping process by automatically creating a service along with the workload, using the service port and type that you select.

      Service Types​

      There are several types of services available in Rancher. The descriptions below are sourced from the Kubernetes Documentation.

      • ClusterIP

        Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default ServiceType.

      • NodePort

        Exposes the service on each Node’s IP at a static port (the NodePort). A ClusterIP service, to which the NodePort service will route, is automatically created. You’ll be able to contact the NodePort service, from outside the cluster, by requesting <NodeIP>:<NodePort>.

      • LoadBalancer

        Exposes the service externally using a cloud provider’s load balancer. NodePort and ClusterIP services, to which the external load balancer will route, are automatically created.

      Workload Options​

      This section of the documentation contains instructions for deploying workloads and using workload options.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides.html b/v2.0-v2.4/reference-guides.html index f30d71d2cce..865cc932483 100644 --- a/v2.0-v2.4/reference-guides.html +++ b/v2.0-v2.4/reference-guides.html @@ -5,13 +5,13 @@ Reference Guides | Rancher Manager - +
      Version: v2.0-v2.4

      Reference Guides

      Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

      These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

      The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

      Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/about-the-api/api-tokens.html b/v2.0-v2.4/reference-guides/about-the-api/api-tokens.html index 0daf7ed99de..68777cc45c2 100644 --- a/v2.0-v2.4/reference-guides/about-the-api/api-tokens.html +++ b/v2.0-v2.4/reference-guides/about-the-api/api-tokens.html @@ -5,14 +5,14 @@ API Tokens | Rancher Manager - +
      Version: v2.0-v2.4

      API Tokens

      By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. Tokens are not invalidated by changing a password.

      You can deactivate API tokens by deleting them or by deactivating the user account.

      Deleting tokens​

      To delete a token,

      1. Go to the list of all tokens in the Rancher API view at https://<Rancher-Server-IP>/v3/tokens.

      2. Access the token you want to delete by its ID. For example, https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt

      3. Click Delete.

      Here is the complete list of tokens that are generated with ttl=0:

      TokenDescription
      kubeconfig-*Kubeconfig token
      kubectl-shell-*Access to kubectl shell in the browser
      agent-*Token for agent deployment
      compose-token-*Token for compose
      helm-token-*Token for Helm chart deployment
      *-pipeline*Pipeline token for project
      telemetry-*Telemetry token
      drain-node-*Token for drain (we use kubectl for drain because there is no native Kubernetes API)

      Setting TTL on Kubeconfig Tokens​

      Available as of v2.4.6

      Starting Rancher v2.4.6, admins can set a global TTL on Kubeconfig tokens. Once the token expires the kubectl command will require the user to authenticate to Rancher.

      Note:

      Existing kubeconfig tokens won't be updated with the new TTL. Admins can delete old kubeconfig tokens.

      1. Disable the kubeconfig-generate-token setting in the Rancher API view at https://<Rancher-Server-IP/v3/settings/kubeconfig-generate-token. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. The kubeconfig file will now provide a command to login to Rancher.

      2. Edit the setting and set the value to false.

      3. Go to setting kubeconfig-token-ttl-minutes in the Rancher API view at https://<Rancher-Server-IP/v3/settings/kubeconfig-token-ttl-minutes. By default, kubeconfig-token-ttl-minutes is 960 (16 hours).

      4. Edit the setting and set the value to desired duration in minutes. Note: This value cannot exceed max-ttl of API tokens.(https://<Rancher-Server-IP/v3/settings/auth-token-max-ttl-minutes). In Rancher v2.4.6, auth-token-max-ttl-minutes is set to 1440 (24 hours) by default. Starting Rancher v2.4.7, auth-token-max-ttl-minutes would default to 0 allowing tokens to never expire, similar to v2.4.5.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/best-practices/containers.html b/v2.0-v2.4/reference-guides/best-practices/containers.html index 7d9d502591c..a0cdbdade38 100644 --- a/v2.0-v2.4/reference-guides/best-practices/containers.html +++ b/v2.0-v2.4/reference-guides/best-practices/containers.html @@ -5,13 +5,13 @@ Tips for Setting Up Containers | Rancher Manager - +
      Version: v2.0-v2.4

      Tips for Setting Up Containers

      Running well-built containers can greatly impact the overall performance and security of your environment.

      Below are a few tips for setting up your containers.

      For a more detailed discussion of security for containers, you can also refer to Rancher's Guide to Container Security.

      Use a Common Container OS​

      When possible, you should try to standardize on a common container base OS.

      Smaller distributions such as Alpine and BusyBox reduce container image size and generally have a smaller attack/vulnerability surface.

      Popular distributions such as Ubuntu, Fedora, and CentOS are more field-tested and offer more functionality.

      Start with a FROM scratch container​

      If your microservice is a standalone static binary, you should use a FROM scratch container.

      The FROM scratch container is an official Docker image that is empty so that you can use it to design minimal images.

      This will have the smallest attack surface and smallest image size.

      Run Container Processes as Unprivileged​

      When possible, use a non-privileged user when running processes within your container. While container runtimes provide isolation, vulnerabilities and attacks are still possible. Inadvertent or accidental host mounts can also be impacted if the container is running as root. For details on configuring a security context for a pod or container, refer to the Kubernetes docs.

      Define Resource Limits​

      Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices.

      In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs.

      When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

      The Kubernetes docs have more information on how resource limits can be set at the container level and the namespace level.

      Define Resource Requirements​

      You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining resources.requests in the resource requests field in a pod's container spec. For details, refer to the Kubernetes docs.

      Note: If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace.

      It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load.

      Liveness and Readiness Probes​

      Set up liveness and readiness probes for your container. Unless your container completely crashes, Kubernetes will not know it's unhealthy unless you create an endpoint or mechanism that can report container status. Alternatively, make sure your container halts and crashes if unhealthy.

      The Kubernetes docs show how to configure liveness and readiness probes for containers.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/best-practices/deployment-strategies.html b/v2.0-v2.4/reference-guides/best-practices/deployment-strategies.html index 8ea05d8ce60..c0bb806bac1 100644 --- a/v2.0-v2.4/reference-guides/best-practices/deployment-strategies.html +++ b/v2.0-v2.4/reference-guides/best-practices/deployment-strategies.html @@ -5,13 +5,13 @@ Rancher Deployment Strategies | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher Deployment Strategies

      There are two recommended deployment strategies. Each one has its own pros and cons. Read more about which one would fit best for your use case:

      Hub and Spoke Strategy

      In this deployment scenario, there is a single Rancher control plane managing Kubernetes clusters across the globe. The control plane would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies.

      Pros​

      • Environments could have nodes and network connectivity across regions.
      • Single control plane interface to view/see all regions and environments.
      • Kubernetes does not require Rancher to operate and can tolerate losing connectivity to the Rancher control plane.

      Cons​

      • Subject to network latencies.
      • If the control plane goes out, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually.

      Regional Strategy

      In the regional deployment model a control plane is deployed in close proximity to the compute nodes.

      Pros​

      • Rancher functionality in regions stay operational if a control plane in another region goes down.
      • Network latency is greatly reduced, improving the performance of functionality in Rancher.
      • Upgrades of the Rancher control plane can be done independently per region.

      Cons​

      • Overhead of managing multiple Rancher installations.
      • Visibility across global Kubernetes clusters requires multiple interfaces/panes of glass.
      • Deploying multi-cluster apps in Rancher requires repeating the process for each Rancher server.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/best-practices/deployment-types.html b/v2.0-v2.4/reference-guides/best-practices/deployment-types.html index 81a6e3b8ab2..f3a36881c21 100644 --- a/v2.0-v2.4/reference-guides/best-practices/deployment-types.html +++ b/v2.0-v2.4/reference-guides/best-practices/deployment-types.html @@ -5,13 +5,13 @@ Tips for Running Rancher | Rancher Manager - +
      Version: v2.0-v2.4

      Tips for Running Rancher

      A high-availability Kubernetes installation, defined as an installation of Rancher on a Kubernetes cluster with at least three nodes, should be used in any production installation of Rancher, as well as any installation deemed "important." Multiple Rancher instances running on multiple nodes ensure high availability that cannot be accomplished with a single node environment.

      When you set up your high-availability Rancher installation, consider the following:

      Run Rancher on a Separate Cluster​

      Don't run other workloads or microservices in the Kubernetes cluster that Rancher is installed on.

      Don't Run Rancher on a Hosted Kubernetes Environment​

      When the Rancher server is installed on a Kubernetes cluster, it should not be run in a hosted Kubernetes environment such as Google's GKE, Amazon's EKS, or Microsoft's AKS. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations.

      It is strongly recommended to use hosted infrastructure such as Amazon's EC2 or Google's GCE instead. When you create a cluster using RKE on an infrastructure provider, you can configure the cluster to create etcd snapshots as a backup. You can then use RKE or Rancher to restore your cluster from one of these snapshots. In a hosted Kubernetes environment, this backup and restore functionality is not supported.

      Make sure nodes are configured correctly for Kubernetes​

      It's important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node, checking that all correct ports are opened, and deploying with ssd backed etcd. More details can be found in the kubernetes docs and etcd's performance op guide

      When using RKE: Backup the Statefile​

      RKE keeps record of the cluster state in a file called cluster.rkestate. This file is important for the recovery of a cluster and/or the continued maintenance of the cluster through RKE. Because this file contains certificate material, we strongly recommend encrypting this file before backing up. After each run of rke up you should backup the state file.

      Run All Nodes in the Cluster in the Same Datacenter​

      For best performance, run all three of your nodes in the same geographic datacenter. If you are running nodes in the cloud, such as AWS, run each node in a separate Availability Zone. For example, launch node 1 in us-west-2a, node 2 in us-west-2b, and node 3 in us-west-2c.

      Development and Production Environments Should be Similar​

      It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration.

      Monitor Your Clusters to Plan Capacity​

      The Rancher server's Kubernetes cluster should run within the system and hardware requirements as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.

      However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types.

      Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus.

      After you enable monitoring in the cluster, you can set up a notification channel and cluster alerts to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/best-practices/management.html b/v2.0-v2.4/reference-guides/best-practices/management.html index 6d7eafe60cb..00a63eec5f6 100644 --- a/v2.0-v2.4/reference-guides/best-practices/management.html +++ b/v2.0-v2.4/reference-guides/best-practices/management.html @@ -5,13 +5,13 @@ Tips for Scaling, Security and Reliability | Rancher Manager - +
      Version: v2.0-v2.4

      Tips for Scaling, Security and Reliability

      Rancher allows you to set up numerous combinations of configurations. Some configurations are more appropriate for development and testing, while there are other best practices for production environments for maximum availability and fault tolerance. The following best practices should be followed for production.

      Tips for Preventing and Handling Problems

      These tips can help you solve problems before they happen.

      Run Rancher on a Supported OS and Supported Docker Version​

      Rancher is container-based and can potentially run on any Linux-based operating system. However, only operating systems listed in the requirements documentation should be used for running Rancher, along with a supported version of Docker. These versions have been most thoroughly tested and can be properly supported by the Rancher Support team.

      Upgrade Your Kubernetes Version​

      Keep your Kubernetes cluster up to date with a recent and supported version. Typically the Kubernetes community will support the current version and previous three minor releases (for example, 1.14.x, 1.13.x, 1.12.x, and 1.11.x). After a new version is released, the third-oldest supported version reaches EOL (End of Life) status. Running on an EOL release can be a risk if a security issues are found and patches are not available. The community typically makes minor releases every quarter (every three months).

      Rancher’s SLAs are not community dependent, but as Kubernetes is a community-driven software, the quality of experience will degrade as you get farther away from the community's supported target.

      Kill Pods Randomly During Testing​

      Run chaoskube or a similar mechanism to randomly kill pods in your test environment. This will test the resiliency of your infrastructure and the ability of Kubernetes to self-heal. It's not recommended to run this in your production environment.

      Deploy Complicated Clusters with Terraform​

      Rancher's "Add Cluster" UI is preferable for getting started with Kubernetes cluster orchestration or for simple use cases. However, for more complex or demanding use cases, it is recommended to use a CLI/API driven approach. Terraform is recommended as the tooling to implement this. When you use Terraform with version control and a CI/CD environment, you can have high assurances of consistency and reliability when deploying Kubernetes clusters. This approach also gives you the most customization options.

      Rancher maintains a Terraform provider for working with Rancher 2.0 Kubernetes. It is called the Rancher2 Provider.

      Upgrade Rancher in a Staging Environment​

      All upgrades, both patch and feature upgrades, should be first tested on a staging environment before production is upgraded. The more closely the staging environment mirrors production, the higher chance your production upgrade will be successful.

      Renew Certificates Before they Expire​

      Multiple people in your organization should set up calendar reminders for certificate renewal. Consider renewing the certificate two weeks to one month in advance. If you have multiple certificates to track, consider using monitoring and alerting mechanisms to track certificate expiration.

      Rancher-provisioned Kubernetes clusters will use certificates that expire in one year. Clusters provisioned by other means may have a longer or shorter expiration.

      Certificates can be renewed for Rancher-provisioned clusters through the Rancher user interface.

      Enable Recurring Snapshots for Backing up and Restoring the Cluster​

      Make sure etcd recurring snapshots are enabled. Extend the snapshot retention to a period of time that meets your business needs. In the event of a catastrophic failure or deletion of data, this may be your only recourse for recovery. For details about configuring snapshots, refer to the RKE documentation or the Rancher documentation on backups.

      Provision Clusters with Rancher​

      When possible, use Rancher to provision your Kubernetes cluster rather than importing a cluster. This will ensure the best compatibility and supportability.

      Use Stable and Supported Rancher Versions for Production​

      Do not upgrade production environments to alpha, beta, release candidate (rc), or "latest" versions. These early releases are often not stable and may not have a future upgrade path.

      When installing or upgrading a non-production environment to an early release, anticipate problems such as features not working, data loss, outages, and inability to upgrade without a reinstall.

      Make sure the feature version you are upgrading to is considered "stable" as determined by Rancher. Use the beta, release candidate, and "latest" versions in a testing, development, or demo environment to try out new features. Feature version upgrades, for example 2.1.x to 2.2.x, should be considered as and when they are released. Some bug fixes and most features are not back ported into older versions.

      Keep in mind that Rancher does End of Life support for old versions, so you will eventually want to upgrade if you want to continue to receive patches.

      For more detail on what happens during the Rancher product lifecycle, refer to the Support Maintenance Terms.

      Network Topology

      These tips can help Rancher work more smoothly with your network.

      Use Low-latency Networks for Communication Within Clusters​

      Kubernetes clusters are best served by low-latency networks. This is especially true for the control plane components and etcd, where lots of coordination and leader election traffic occurs. Networking between Rancher server and the Kubernetes clusters it manages are more tolerant of latency.

      Allow Rancher to Communicate Directly with Clusters​

      Limit the use of proxies or load balancers between Rancher server and Kubernetes clusters. As Rancher is maintaining a long-lived web sockets connection, these intermediaries can interfere with the connection lifecycle as they often weren't configured with this use case in mind.

      Tips for Scaling and Reliability

      These tips can help you scale your cluster more easily.

      Use One Kubernetes Role Per Host​

      Separate the etcd, control plane, and worker roles onto different hosts. Don't assign multiple roles to the same host, such as a worker and control plane. This will give you maximum scalability.

      Run the Control Plane and etcd on Virtual Machines​

      Run your etcd and control plane nodes on virtual machines where you can scale vCPU and memory easily if needed in the future.

      Use at Least Three etcd Nodes​

      Provision 3 or 5 etcd nodes. Etcd requires a quorum to determine a leader by the majority of nodes, therefore it is not recommended to have clusters of even numbers. Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters.

      Use at Least Three Control Plane Nodes​

      Provision three or more control plane nodes. Some control plane components, such as the kube-apiserver, run in active-active mode and will give you more scalability. Other components such as kube-scheduler and kube-controller run in active-passive mode (leader elect) and give you more fault tolerance.

      Monitor Your Cluster​

      Closely monitor and scale your nodes as needed. You should enable cluster monitoring and use the Prometheus metrics and Grafana visualization options as a starting point.

      Tips for Security

      Below are some basic tips for increasing security in Rancher. For more detailed information about securing your cluster, you can refer to these resources:

      Update Rancher with Security Patches​

      Keep your Rancher installation up to date with the latest patches. Patch updates have important software fixes and sometimes have security fixes. When patches with security fixes are released, customers with Rancher licenses are notified by e-mail. These updates are also posted on Rancher's forum.

      Report Security Issues Directly to Rancher​

      If you believe you have uncovered a security-related problem in Rancher, please communicate this immediately and discretely to the Rancher team (security@rancher.com). Posting security issues on public forums such as Twitter, Rancher Slack, GitHub, etc. can potentially compromise security for all Rancher customers. Reporting security issues discretely allows Rancher to assess and mitigate the problem. Security patches are typically given high priority and released as quickly as possible.

      Only Upgrade One Component at a Time​

      In addition to Rancher software updates, closely monitor security fixes for related software, such as Docker, Linux, and any libraries used by your workloads. For production environments, try to avoid upgrading too many entities during a single maintenance window. Upgrading multiple components can make it difficult to root cause an issue in the event of a failure. As business requirements allow, upgrade one component at a time.

      Tips for Multi-Tenant Clusters

      Namespaces​

      Each tenant should have their own unique namespaces within the cluster. This avoids naming conflicts and allows resources to be only visible to their owner through use of RBAC policy

      Project Isolation​

      Use Rancher's Project Isolation to automatically generate Network Policy between Projects (sets of Namespaces). This further protects workloads from interference

      Resource Limits​

      Enforce use of sane resource limit definitions for every deployment in your cluster. This not only protects the owners of the deployment, but the neighboring resources from other tenants as well. Remember, namespaces do not isolate at the node level, so over-consumption of resources on a node affects other namespace deployments. Admission controllers can be written to require resource limit definitions

      Resource Requirements​

      Enforce use of resource requirement definitions for each deployment in your cluster. This enables the scheduler to appropriately schedule workloads. Otherwise you will eventually end up with over-provisioned nodes.

      Class of Service and Kubernetes Clusters

      A class of service describes the expectations around cluster uptime, durability, and duration of maintenance windows. Typically organizations group these characteristics into labels such as "dev" or "prod"

      Consider fault domains​

      Kubernetes clusters can span multiple classes of service, however it is important to consider the ability for one workload to affect another. Without proper deployment practices such as resource limits, requirements, etc, a deployment that is not behaving well has the potential to impact the health of the cluster. In a "dev" environment it is common for end-users to exercise less caution with deployments, thus increasing the chance of such behavior. Sharing this behavior with your production workload increases risk.

      Upgrade risks​

      Upgrades of Kubernetes are not without risk, the best way to predict the outcome of an upgrade is try it on a cluster of similar load and use case as your production cluster. This is where having non-prod class of service clusters can be advantageous.

      Resource Efficiency​

      Clusters can be built with varying degrees of redundancy. In a class of service with low expectations for uptime, resources and cost can be conserved by building clusters without redundant Kubernetes control components. This approach may also free up more budget/resources to increase the redundancy at the production level

      Network Security

      In general, you can use network security best practices in your Rancher and Kubernetes clusters. Consider the following:

      Use a Firewall Between your Hosts and the Internet​

      Firewalls should be used between your hosts and the Internet (or corporate Intranet). This could be enterprise firewall appliances in a datacenter or SDN constructs in the cloud, such as VPCs, security groups, ingress, and egress rules. Try to limit inbound access only to ports and IP addresses that require it. Outbound access can be shut off (air gap) if environment sensitive information that requires this restriction. If available, use firewalls with intrusion detection and DDoS prevention.

      Run Periodic Security Scans​

      Run security and penetration scans on your environment periodically. Even with well design infrastructure, a poorly designed microservice could compromise the entire environment.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cli-with-rancher/kubectl-utility.html b/v2.0-v2.4/reference-guides/cli-with-rancher/kubectl-utility.html index 384ab9c01bf..b1d2f03c63b 100644 --- a/v2.0-v2.4/reference-guides/cli-with-rancher/kubectl-utility.html +++ b/v2.0-v2.4/reference-guides/cli-with-rancher/kubectl-utility.html @@ -5,14 +5,14 @@ kubectl Utility | Rancher Manager - +
      Version: v2.0-v2.4

      kubectl

      Interact with Rancher using kubectl.

      kubectl Utility​

      Install the kubectl utility. See install kubectl.

      Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on Kubeconfig, copying contents, and putting them into your ~/.kube/config file.

      Run kubectl cluster-info or kubectl get pods successfully.

      Authentication with kubectl and kubeconfig Tokens with TTL​

      Requirements

      If admins have enforced TTL on kubeconfig tokens, the kubeconfig file requires the Rancher CLI to be present in your PATH when you run kubectl. Otherwise, you’ll see an error like: Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH.

      This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:

      1. Local
      2. Active Directory (LDAP only)
      3. FreeIPA
      4. OpenLDAP
      5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth

      When you first run kubectl, for example, kubectl get pods, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under ./.cache/token. This token is valid until it expires, or gets deleted from the Rancher server. Upon expiration, the next kubectl get pods will ask you to log in with the Rancher server again.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cli-with-rancher/rancher-cli.html b/v2.0-v2.4/reference-guides/cli-with-rancher/rancher-cli.html index d3b177aa434..86aabb80622 100644 --- a/v2.0-v2.4/reference-guides/cli-with-rancher/rancher-cli.html +++ b/v2.0-v2.4/reference-guides/cli-with-rancher/rancher-cli.html @@ -5,13 +5,13 @@ Rancher CLI | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher CLI

      The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.

      Download Rancher CLI​

      The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

      1. In the upper left corner, click ☰.
      2. At the bottom, click v2.6.x, where v2.6.x is a hyperlinked text indicating the installed Rancher version.
      3. Under the CLI Downloads section, there are links to download the binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

      Requirements​

      After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:

      • Your Rancher Server URL, which is used to connect to Rancher Server.
      • An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see Creating an API Key.

      CLI Authentication​

      Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace <BEARER_TOKEN> and <SERVER_URL> with your information):

      $ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>

      If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.

      Project Selection​

      Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a project to work on, use the command ./rancher context switch. When you enter this command, a list of available projects displays. Enter a number to choose your project.

      Example: ./rancher context switch Output

      User:rancher-cli-directory user$ ./rancher context switch
      NUMBER    CLUSTER NAME   PROJECT ID              PROJECT NAME
      1         cluster-2      c-7q96s:p-h4tmb         project-2
      2         cluster-2      c-7q96s:project-j6z6d   Default
      3         cluster-1      c-lchzv:p-xbpdt         project-1
      4         cluster-1      c-lchzv:project-s2mch   Default
      Select a Project:

      After you enter a number, the console displays a message that you've changed projects.

      INFO[0005] Setting new context to project project-1
      INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json

      Ensure you can run rancher kubectl get pods successfully.

      Commands​

      The following commands are available for use in Rancher CLI.

      CommandResult
      apps, [app]Performs operations on catalog applications (i.e., individual Helm charts) or Rancher charts.
      catalogPerforms operations on catalogs.
      clusters, [cluster]Performs operations on your clusters.
      contextSwitches between Rancher projects. For an example, see Project Selection.
      inspect [OPTIONS] [RESOURCEID RESOURCENAME]Displays details about Kubernetes resources or Rancher resources (i.e.: projects and workloads). Specify resources by name or ID.
      kubectlRuns kubectl commands.
      login, [l]Logs into a Rancher Server. For an example, see CLI Authentication.
      namespaces, [namespace]Performs operations on namespaces.
      nodes, [node]Performs operations on nodes.
      projects, [project]Performs operations on projects.
      psDisplays workloads in a project.
      settings, [setting]Shows the current settings for your Rancher Server.
      sshConnects to one of your cluster nodes using the SSH protocol.
      help, [h]Shows a list of commands or help for one command.

      Rancher CLI Help​

      Once logged into Rancher Server using the CLI, enter ./rancher --help for a list of commands.

      All commands accept the --help flag, which documents each command's usage.

      Limitations​

      The Rancher CLI cannot be used to install dashboard apps or Rancher feature charts.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html index bc71ce3db6c..20209ef6142 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html @@ -5,13 +5,13 @@ EC2 Node Template Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      EC2 Node Template Configuration

      For more details about EC2, nodes, refer to the official documentation for the EC2 Management Console.

      Region​

      In the Region field, select the same region that you used when creating your cloud credentials.

      Cloud Credentials​

      Your AWS account access information, stored in a cloud credential.

      See Amazon Documentation: Creating Access Keys how to create an Access Key and Secret Key.

      See Amazon Documentation: Creating IAM Policies (Console) how to create an IAM policy.

      See Amazon Documentation: Adding Permissions to a User (Console) how to attach an IAM

      See our three example JSON policies:

      Authenticate & Configure Nodes​

      Choose an availability zone and network settings for your cluster.

      Security Group​

      Choose the default security group or configure a security group.

      Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group.

      Instance Options​

      Configure the instances that will be created. Make sure you configure the correct SSH User for the configured AMI.

      If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a Kubernetes Cloud Provider, you will need an additional permission in your policy. See Example IAM policy with PassRole for an example policy.

      Engine Options​

      In the Engine Options section of the node template, you can configure the Docker daemon. You may want to specify the docker version or a Docker registry mirror.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html index 9d220244294..96869b7443d 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html @@ -5,13 +5,13 @@ Azure Node Template Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      Azure Node Template Configuration

      For more information about Azure, refer to the official Azure documentation.

      Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

      • Placement sets the geographical region where your cluster is hosted and other location metadata.
      • Network configures the networking used in your cluster.
      • Instance customizes your VM configuration.

      The Docker daemon configuration options include:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html index 6c5a9ac9856..9bf28275fcd 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html @@ -5,13 +5,13 @@ DigitalOcean Node Template Configuration | Rancher Manager - +
      Version: v2.0-v2.4

      DigitalOcean Node Template Configuration

      Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

      Droplet Options​

      The Droplet Options provision your cluster's geographical region and specifications.

      Docker Daemon​

      The Docker daemon configuration options include:

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/prior-to-v2.0.4.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/prior-to-v2.0.4.html index 4de4ce62ddf..530b3f81568 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/prior-to-v2.0.4.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/prior-to-v2.0.4.html @@ -5,13 +5,13 @@ vSphere Node Template Configuration in Rancher before v2.0.4 | Rancher Manager - +
      Version: v2.0-v2.4

      vSphere Node Template Configuration in Rancher before v2.0.4

      Account Access​

      In the Account Access section, enter the vCenter FQDN or IP address and the credentials for the vSphere user account.

      ParameterRequiredDescription
      vCenter or ESXi Server*IP or FQDN of the vCenter or ESXi server used for managing VMs. Enter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
      Port*Port to use when connecting to the server. Defaults to 443.
      Username*vCenter/ESXi user to authenticate with the server.
      Password*User's password.

      Scheduling​

      Choose what hypervisor the virtual machine will be scheduled to.

      ParameterRequiredDescription
      Data Center*Name/path of the datacenter to create VMs in.
      PoolName/path of the resource pool to schedule the VMs in. If not specified, the default resource pool is used.
      HostName/path of the host system to schedule VMs in. If specified, the host system's pool will be used and the Pool parameter will be ignored.
      Network*Name of the VM network to attach VMs to.
      Data Store*Datastore to store the VM disks.
      FolderName of a folder in the datacenter to create the VMs in. Must already exist. The folder name should be prefaced with vm/ in your vSphere config file.

      Instance Options​

      In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

      Only VMs booting from RancherOS ISO are supported.

      Ensure that the OS ISO URL contains the URL of the VMware ISO release for RancherOS: rancheros-vmware.iso.

      ParameterRequiredDescription
      CPUs*Number of vCPUS to assign to VMs.
      Memory*Amount of memory to assign to VMs.
      Disk*Size of the disk (in MB) to attach to the VMs.
      Cloud InitURL of a RancherOS cloud-config file to provision VMs with. This file allows further customization of the RancherOS operating system, such as network configuration, DNS servers, or system daemons.
      OS ISO URL*URL of a RancherOS vSphere ISO file to boot the VMs from. You can find URLs for specific versions in the Rancher OS GitHub Repo.
      Configuration ParametersAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

      Disk UUIDs​

      In order to provision nodes with RKE, all nodes must be configured with disk UUIDs. Follow these instructions to enable UUIDs for the nodes in your vSphere cluster.

      To enable disk UUIDs for all VMs created for a cluster,

      1. Navigate to the Node Templates in the Rancher UI while logged in as an administrator.

      2. Add or edit an existing vSphere node template.

      3. Under Instance Options click on Add Parameter.

      4. Enter disk.enableUUID as key with a value of TRUE.

      5. Click Create or Save.

      Result: The disk UUID is enabled in the vSphere node template.

      Node Tags and Custom Attributes​

      These attributes allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

      Optionally, you can:

      • Provide a set of configuration parameters (instance-options) for the VMs.
      • Assign labels to the VMs that can be used as a base for scheduling rules in the cluster.
      • Customize the configuration of the Docker daemon on the VMs that will be created.

      Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

      Cloud Init​

      Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

      You may specify the URL of a RancherOS cloud-config.yaml file in the the Cloud Init field. Refer to the RancherOS Documentation for details on the supported configuration directives. Note that the URL must be network accessible from the VMs created by the template.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.0.4.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.0.4.html index 82b2317f3cd..1675f692e63 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.0.4.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.0.4.html @@ -5,13 +5,13 @@ vSphere Node Template Configuration in Rancher v2.0.4 | Rancher Manager - +
      Version: v2.0-v2.4

      vSphere Node Template Configuration in Rancher v2.0.4

      Account Access​

      In the Account Access section, enter the vCenter FQDN or IP address and the credentials for the vSphere user account.

      ParameterRequiredDescription
      vCenter or ESXi Server*IP or FQDN of the vCenter or ESXi server used for managing VMs. Enter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
      Port*Port to use when connecting to the server. Defaults to 443.
      Username*vCenter/ESXi user to authenticate with the server.
      Password*User's password.

      Scheduling​

      Choose what hypervisor the virtual machine will be scheduled to.

      ParameterRequiredDescription
      Data Center*Name/path of the datacenter to create VMs in.
      PoolName/path of the resource pool to schedule the VMs in. If not specified, the default resource pool is used.
      HostName/path of the host system to schedule VMs in. If specified, the host system's pool will be used and the Pool parameter will be ignored.
      Network*Name of the VM network to attach VMs to.
      Data Store*Datastore to store the VM disks.
      FolderName of a folder in the datacenter to create the VMs in. Must already exist. The folder name should be prefaced with vm/ in your vSphere config file.

      Instance Options​

      In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

      Only VMs booting from RancherOS ISO are supported.

      Ensure that the OS ISO URL contains the URL of the VMware ISO release for RancherOS: rancheros-vmware.iso.

      ParameterRequiredDescription
      CPUs*Number of vCPUS to assign to VMs.
      Memory*Amount of memory to assign to VMs.
      Disk*Size of the disk (in MB) to attach to the VMs.
      Cloud InitURL of a RancherOS cloud-config file to provision VMs with. This file allows further customization of the RancherOS operating system, such as network configuration, DNS servers, or system daemons.
      OS ISO URL*URL of a RancherOS vSphere ISO file to boot the VMs from. You can find URLs for specific versions in the Rancher OS GitHub Repo.
      Configuration ParametersAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

      Node Tags and Custom Attributes​

      These attributes allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

      Optionally, you can:

      • Provide a set of configuration parameters (instance-options) for the VMs.
      • Assign labels to the VMs that can be used as a base for scheduling rules in the cluster.
      • Customize the configuration of the Docker daemon on the VMs that will be created.

      Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

      Cloud Init​

      Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

      You may specify the URL of a RancherOS cloud-config.yaml file in the the Cloud Init field. Refer to the RancherOS Documentation for details on the supported configuration directives. Note that the URL must be network accessible from the VMs created by the template.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.2.0.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.2.0.html index 3c700df4c85..773100093af 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.2.0.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.2.0.html @@ -5,13 +5,13 @@ vSphere Node Template Configuration in Rancher v2.2.0 | Rancher Manager - +
      Version: v2.0-v2.4

      vSphere Node Template Configuration in Rancher v2.2.0

      Account Access​

      ParameterRequiredDescription
      Cloud Credentials*Your vSphere account access information, stored in a cloud credential.

      Your cloud credential has these fields:

      Credential FieldDescription
      vCenter or ESXi ServerEnter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
      PortOptional: configure configure the port of the vCenter or ESXi server.
      Username and passwordEnter your vSphere login username and password.

      Scheduling​

      Choose what hypervisor the virtual machine will be scheduled to.

      ParameterRequiredDescription
      Data Center*Name/path of the datacenter to create VMs in.
      PoolName/path of the resource pool to schedule the VMs in. If not specified, the default resource pool is used.
      HostName/path of the host system to schedule VMs in. If specified, the host system's pool will be used and the Pool parameter will be ignored.
      Network*Name of the VM network to attach VMs to.
      Data Store*Datastore to store the VM disks.
      FolderName of a folder in the datacenter to create the VMs in. Must already exist. The folder name should be prefaced with vm/ in your vSphere config file.

      Instance Options​

      In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

      Only VMs booting from RancherOS ISO are supported.

      Ensure that the OS ISO URL contains the URL of the VMware ISO release for RancherOS: rancheros-vmware.iso.

      ParameterRequiredDescription
      CPUs*Number of vCPUS to assign to VMs.
      Memory*Amount of memory to assign to VMs.
      Disk*Size of the disk (in MB) to attach to the VMs.
      Cloud InitURL of a RancherOS cloud-config file to provision VMs with. This file allows further customization of the RancherOS operating system, such as network configuration, DNS servers, or system daemons.
      OS ISO URL*URL of a RancherOS vSphere ISO file to boot the VMs from. You can find URLs for specific versions in the Rancher OS GitHub Repo.
      Configuration ParametersAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

      Node Tags and Custom Attributes​

      These attributes allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

      Optionally, you can:

      • Provide a set of configuration parameters (instance-options) for the VMs.
      • Assign labels to the VMs that can be used as a base for scheduling rules in the cluster.
      • Customize the configuration of the Docker daemon on the VMs that will be created.

      Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

      Cloud Init​

      Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

      You may specify the URL of a RancherOS cloud-config.yaml file in the the Cloud Init field. Refer to the RancherOS Documentation for details on the supported configuration directives. Note that the URL must be network accessible from the VMs created by the template.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.0.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.0.html index 8d760dee616..00fe3222fdd 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.0.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.0.html @@ -5,13 +5,13 @@ vSphere Node Template Configuration in Rancher v2.3.0 | Rancher Manager - +
      Version: v2.0-v2.4

      vSphere Node Template Configuration in Rancher v2.3.0

      Account Access​

      ParameterRequiredDescription
      Cloud Credentials*Your vSphere account access information, stored in a cloud credential.

      Your cloud credential has these fields:

      Credential FieldDescription
      vCenter or ESXi ServerEnter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
      PortOptional: configure configure the port of the vCenter or ESXi server.
      Username and passwordEnter your vSphere login username and password.

      Scheduling​

      Choose what hypervisor the virtual machine will be scheduled to.

      In the Scheduling section, enter:

      • The name/path of the Data Center to create the VMs in
      • The name of the VM Network to attach to
      • The name/path of the Datastore to store the disks in
      ParameterRequiredDescription
      Data Center*Name/path of the datacenter to create VMs in.
      PoolName/path of the resource pool to schedule the VMs in. If not specified, the default resource pool is used.
      HostName/path of the host system to schedule VMs in. If specified, the host system's pool will be used and the Pool parameter will be ignored.
      Network*Name of the VM network to attach VMs to.
      Data Store*Datastore to store the VM disks.
      FolderName of a folder in the datacenter to create the VMs in. Must already exist. The folder name should be prefaced with vm/ in your vSphere config file.

      Instance Options​

      In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

      Only VMs booting from RancherOS ISO are supported.

      Ensure that the OS ISO URL contains the URL of the VMware ISO release for RancherOS: rancheros-vmware.iso.

      ParameterRequiredDescription
      CPUs*Number of vCPUS to assign to VMs.
      Memory*Amount of memory to assign to VMs.
      Disk*Size of the disk (in MB) to attach to the VMs.
      Cloud InitURL of a RancherOS cloud-config file to provision VMs with. This file allows further customization of the RancherOS operating system, such as network configuration, DNS servers, or system daemons.
      OS ISO URL*URL of a RancherOS vSphere ISO file to boot the VMs from. You can find URLs for specific versions in the Rancher OS GitHub Repo.
      Configuration ParametersAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

      Node Tags and Custom Attributes​

      These attributes allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

      Optionally, you can:

      • Provide a set of configuration parameters (instance-options) for the VMs.
      • Assign labels to the VMs that can be used as a base for scheduling rules in the cluster.
      • Customize the configuration of the Docker daemon on the VMs that will be created.

      Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

      Cloud Init​

      Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

      You may specify the URL of a RancherOS cloud-config.yaml file in the the Cloud Init field. Refer to the RancherOS Documentation for details on the supported configuration directives. Note that the URL must be network accessible from the VMs created by the template.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.3.html b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.3.html index c4aafdfc4e4..4bb1ebd2aa5 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.3.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere/v2.3.3.html @@ -5,13 +5,13 @@ vSphere Node Template Configuration in Rancher v2.3.3 | Rancher Manager - +
      Version: v2.0-v2.4

      vSphere Node Template Configuration in Rancher v2.3.3

      Account Access​

      ParameterRequiredDescription
      Cloud Credentials*Your vSphere account access information, stored in a cloud credential.

      Your cloud credential has these fields:

      Credential FieldDescription
      vCenter or ESXi ServerEnter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
      PortOptional: configure configure the port of the vCenter or ESXi server.
      Username and passwordEnter your vSphere login username and password.

      Scheduling​

      Choose what hypervisor the virtual machine will be scheduled to.

      The fields in the Scheduling section should auto-populate with the data center and other scheduling options that are available to you in vSphere.

      FieldRequiredExplanation
      Data Center*Choose the name/path of the data center where the VM will be scheduled.
      Resource PoolName of the resource pool to schedule the VMs in. Resource pools can be used to partition available CPU and memory resources of a standalone host or cluster, and they can also be nested. Leave blank for standalone ESXi. If not specified, the default resource pool is used.
      Data Store*If you have a data store cluster, you can toggle the Data Store field. This lets you select a data store cluster where your VM will be scheduled to. If the field is not toggled, you can select an individual disk.
      FolderName of a folder in the datacenter to create the VMs in. Must already exist. The VM folders in this dropdown menu directly correspond to your VM folders in vSphere. The folder name should be prefaced with vm/ in your vSphere config file.
      HostThe IP of the host system to schedule VMs in. Leave this field blank for a standalone ESXi or for a cluster with DRS (Distributed Resource Scheduler). If specified, the host system's pool will be used and the Resource Pool parameter will be ignored.

      Instance Options​

      In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

      ParameterRequiredDescription
      CPUs*Number of vCPUS to assign to VMs.
      Memory*Amount of memory to assign to VMs.
      Disk*Size of the disk (in MB) to attach to the VMs.
      Creation method*The method for setting up an operating system on the node. The operating system can be installed from an ISO or from a VM template. Depending on the creation method, you will also have to specify a VM template, content library, existing VM, or ISO. For more information on creation methods, refer to About VM Creation Methods.
      Cloud InitURL of a cloud-config.yml file or URL to provision VMs with. This file allows further customization of the operating system, such as network configuration, DNS servers, or system daemons. The operating system must support cloud-init.
      NetworksName(s) of the network to attach the VM to.
      Configuration Parameters used for guestinfoAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

      About VM Creation Methods​

      In the Creation method field, configure the method used to provision VMs in vSphere. Available options include creating VMs that boot from a RancherOS ISO or creating VMs by cloning from an existing virtual machine or VM template.

      The existing VM or template may use any modern Linux operating system that is configured with support for cloud-init using the NoCloud datasource.

      Choose the way that the VM will be created:

      • Deploy from template: Data Center: Choose a VM template that exists in the data center that you selected.
      • Deploy from template: Content Library: First, select the Content Library that contains your template, then select the template from the populated list Library templates.
      • Clone an existing virtual machine: In the Virtual machine field, choose an existing VM that the new VM will be cloned from.
      • Install from boot2docker ISO: Ensure that the OS ISO URL field contains the URL of a VMware ISO release for RancherOS (rancheros-vmware.iso). Note that this URL must be accessible from the nodes running your Rancher server installation.

      Networks​

      The node template now allows a VM to be provisioned with multiple networks. In the Networks field, you can now click Add Network to add any networks available to you in vSphere.

      Node Tags and Custom Attributes​

      Tags allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

      For tags, all your vSphere tags will show up as options to select from in your node template.

      In the custom attributes, Rancher will let you select all the custom attributes you have already set up in vSphere. The custom attributes are keys and you can enter values for each one.

      Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

      cloud-init​

      Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

      To make use of cloud-init initialization, create a cloud config file using valid YAML syntax and paste the file content in the the Cloud Init field. Refer to the cloud-init documentation. for a commented set of examples of supported cloud config directives.

      Note that cloud-init is not supported when using the ISO creation method.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html b/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html index 91955a91390..f98a0f39070 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html @@ -5,13 +5,13 @@ RKE Cluster Configuration Reference | Rancher Manager - +
      Version: v2.0-v2.4

      RKE Cluster Configuration Reference

      When Rancher installs Kubernetes, it uses RKE as the Kubernetes distribution.

      This section covers the configuration options that are available in Rancher for a new or existing RKE Kubernetes cluster.

      You can configure the Kubernetes options one of two ways:

      • Rancher UI: Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
      • Cluster Config File: Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

      In Rancher v2.0.0-v2.2.x, the RKE cluster config file in Rancher is identical to the cluster config file for the Rancher Kubernetes Engine, which is the tool Rancher uses to provision clusters. In Rancher v2.3.0, the RKE information is still included in the config file, but it is separated from other options, so that the RKE cluster config options are nested under the rancher_kubernetes_engine_config directive. For more information, see the section about the cluster config file.

      This section is a cluster configuration reference, covering the following topics:

      Rancher UI Options​

      When creating a cluster using one of the options described in Rancher Launched Kubernetes, you can configure basic Kubernetes options using the Cluster Options section.

      Kubernetes Version​

      The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on hyperkube.

      Network Provider​

      The Network Provider that the cluster uses. For more details on the different networking providers, please view our Networking FAQ.

      Note: After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications.

      Out of the box, Rancher is compatible with the following network providers:

      Notes on Canal:

      In v2.0.0 - v2.0.4 and v2.0.6, this was the default option for these clusters was Canal with network isolation. With the network isolation automatically enabled, it prevented any pod communication between projects.

      As of v2.0.7, if you use Canal, you also have the option of using Project Network Isolation, which will enable or disable communication between pods in different projects.

      Attention Rancher v2.0.0 - v2.0.6 Users

      • In previous Rancher releases, Canal isolates project network communications with no option to disable it. If you are using any of these Rancher releases, be aware that using Canal prevents all communication between pods in different projects.
      • If you have clusters using Canal and are upgrading to v2.0.7, those clusters enable Project Network Isolation by default. If you want to disable Project Network Isolation, edit the cluster and disable the option.

      Notes on Flannel:

      In v2.0.5, this was the default option, which did not prevent any network isolation between projects.

      Notes on Weave:

      When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a Config File and the Weave Network Plug-in Options.

      Kubernetes Cloud Providers​

      You can configure a Kubernetes cloud provider. If you want to use volumes and storage in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the aws cloud provider.

      Note: If the cloud provider you want to use is not listed as an option, you will need to use the config file option to configure the cloud provider. Please reference the RKE cloud provider documentation on how to configure the cloud provider.

      If you want to see all the configuration options for a cluster, please click Show advanced options on the bottom right. The advanced options are described below:

      Private registries​

      Available as of v2.2.0

      The cluster-level private registry configuration is only used for provisioning clusters.

      There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

      If your private registry requires credentials, you need to pass the credentials to Rancher by editing the cluster options for each cluster that needs to pull images from the registry.

      The private registry configuration option tells Rancher where to pull the system images or addon images that will be used in your cluster.

      • System images are components needed to maintain the Kubernetes cluster.
      • Add-ons are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server.

      See the RKE documentation on private registries for more information on the private registry for components applied during the provisioning of the cluster.

      Authorized Cluster Endpoint​

      Available as of v2.2.0

      Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.

      The authorized cluster endpoint is available only in clusters that Rancher has provisioned using RKE. It is not available for clusters in hosted Kubernetes providers, such as Amazon's EKS. Additionally, the authorized cluster endpoint cannot be enabled for RKE clusters that are imported into Rancher; it is available only on Rancher-launched Kubernetes clusters.

      This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the controlplane role and the default Kubernetes self signed certificates.

      For more detail on how an authorized cluster endpoint works and why it is used, refer to the architecture section.

      We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

      Node Pools​

      For information on using the Rancher UI to set up node pools in an RKE cluster, refer to this page.

      Advanced Options​

      The following options are available when you create clusters in the Rancher UI. They are located under Advanced Options.

      NGINX Ingress​

      Option to enable or disable the NGINX ingress controller.

      Node Port Range​

      Option to change the range of ports that can be used for NodePort services. Default is 30000-32767.

      Metrics Server Monitoring​

      Option to enable or disable Metrics Server.

      Pod Security Policy Support​

      Option to enable and select a default Pod Security Policy. You must have an existing Pod Security Policy configured before you can use this option.

      Docker Version on Nodes​

      Option to require a supported Docker version installed on the cluster nodes that are added to the cluster, or to allow unsupported Docker versions installed on the cluster nodes.

      Docker Root Directory​

      If the nodes you are adding to the cluster have Docker configured with a non-default Docker Root Directory (default is /var/lib/docker), please specify the correct Docker Root Directory in this option.

      Recurring etcd Snapshots​

      Option to enable or disable recurring etcd snapshots.

      Cluster Config File​

      Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration. The system_images option is not supported when creating a cluster with the Rancher UI or API.

      Note: In Rancher v2.0.5 and v2.0.6, the names of services in the Config File (YAML) should contain underscores only: kube_api and kube_controller.

      • To edit an RKE config file directly from the Rancher UI, click Edit as YAML.
      • To read from an existing RKE file, click Read from a file.

      image

      The structure of the config file is different depending on your version of Rancher. Below are example config files for Rancher v2.0.0-v2.2.x and for Rancher v2.3.0+.

      Config File Structure in Rancher v2.3.0+​

      RKE (Rancher Kubernetes Engine) is the tool that Rancher uses to provision Kubernetes clusters. Rancher's cluster config files used to have the same structure as RKE config files, but the structure changed so that in Rancher, RKE cluster config items are separated from non-RKE config items. Therefore, configuration for your cluster needs to be nested under the rancher_kubernetes_engine_config directive in the cluster config file. Cluster config files created with earlier versions of Rancher will need to be updated for this format. An example cluster config file is included below.

      Example Cluster Config File for Rancher v2.3.0+
      #
      # Cluster Config
      #
      docker_root_dir: /var/lib/docker
      enable_cluster_alerting: false
      enable_cluster_monitoring: false
      enable_network_policy: false
      local_cluster_auth_endpoint:
        enabled: true
      #
      # Rancher Config
      #
      rancher_kubernetes_engine_config: # Your RKE template config goes here.
        addon_job_timeout: 30
        authentication:
          strategy: x509
        ignore_docker_version: true
      #
      # # Currently only nginx ingress provider is supported.
      # # To disable ingress controller, set `provider: none`
      # # To enable ingress on specific nodes, use the node_selector, eg:
      #    provider: nginx
      #    node_selector:
      #      app: ingress
      #
        ingress:
          provider: nginx
        kubernetes_version: v1.15.3-rancher3-1
        monitoring:
          provider: metrics-server
      #
      #   If you are using calico on AWS
      #
      #    network:
      #      plugin: calico
      #      calico_network_provider:
      #        cloud_provider: aws
      #
      # # To specify flannel interface
      #
      #    network:
      #      plugin: flannel
      #      flannel_network_provider:
      #      iface: eth1
      #
      # # To specify flannel interface for canal plugin
      #
      #    network:
      #      plugin: canal
      #      canal_network_provider:
      #        iface: eth1
      #
        network:
          options:
            flannel_backend_type: vxlan
          plugin: canal
      #
      #    services:
      #      kube-api:
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kube-controller:
      #        cluster_cidr: 10.42.0.0/16
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kubelet:
      #        cluster_domain: cluster.local
      #        cluster_dns_server: 10.43.0.10
      #
        services:
          etcd:
            backup_config:
              enabled: true
              interval_hours: 12
              retention: 6
              safe_timestamp: false
            creation: 12h
            extra_args:
              election-timeout: 5000
              heartbeat-interval: 500
            gid: 0
            retention: 72h
            snapshot: false
            uid: 0
          kube_api:
            always_pull_images: false
            pod_security_policy: false
            service_node_port_range: 30000-32767
        ssh_agent_auth: false
      windows_prefered_cluster: false

      Config File Structure in Rancher v2.0.0-v2.2.x​

      An example cluster config file is included below.

      Example Cluster Config File for Rancher v2.0.0-v2.2.x
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
      #
      # # Currently only nginx ingress provider is supported.
      # # To disable ingress controller, set `provider: none`
      # # To enable ingress on specific nodes, use the node_selector, eg:
      #    provider: nginx
      #    node_selector:
      #      app: ingress
      #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
      #
      #   If you are using calico on AWS
      #
      #    network:
      #      plugin: calico
      #      calico_network_provider:
      #        cloud_provider: aws
      #
      # # To specify flannel interface
      #
      #    network:
      #      plugin: flannel
      #      flannel_network_provider:
      #      iface: eth1
      #
      # # To specify flannel interface for canal plugin
      #
      #    network:
      #      plugin: canal
      #      canal_network_provider:
      #        iface: eth1
      #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
      #
      #    services:
      #      kube-api:
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kube-controller:
      #        cluster_cidr: 10.42.0.0/16
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kubelet:
      #        cluster_domain: cluster.local
      #        cluster_dns_server: 10.43.0.10
      #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false

      Default DNS provider​

      The table below indicates what DNS provider is deployed by default. See RKE documentation on DNS provider for more information how to configure a different DNS provider. CoreDNS can only be used on Kubernetes v1.12.0 and higher.

      Rancher versionKubernetes versionDefault DNS provider
      v2.2.5 and higherv1.14.0 and higherCoreDNS
      v2.2.5 and higherv1.13.x and lowerkube-dns
      v2.2.4 and loweranykube-dns

      Rancher specific parameters

      Available as of v2.2.0

      Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML):

      docker_root_dir​

      See Docker Root Directory.

      enable_cluster_monitoring​

      Option to enable or disable Cluster Monitoring.

      enable_network_policy​

      Option to enable or disable Project Network Isolation.

      local_cluster_auth_endpoint​

      See Authorized Cluster Endpoint.

      Example:

      local_cluster_auth_endpoint:
        enabled: true
        fqdn: "FQDN"
        ca_certs: "BASE64_CACERT"

      Custom Network Plug-in​

      Available as of v2.2.4

      You can add a custom network plug-in by using the user-defined add-on functionality of RKE. You define any add-on that you want deployed after the Kubernetes cluster is deployed.

      There are two ways that you can specify an add-on:

      For an example of how to configure a custom network plug-in by editing the cluster.yml, refer to the RKE documentation.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html b/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html index 2113beb08d1..94830ec317a 100644 --- a/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html +++ b/v2.0-v2.4/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html @@ -5,13 +5,13 @@ Rancher Agent Options | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher Agent Options

      Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to create a cluster with custom nodes and add the options to the generated docker run command when adding a node.

      For an overview of how Rancher communicates with downstream clusters using node agents, refer to the architecture section.

      General options​

      ParameterEnvironment variableDescription
      --serverCATTLE_SERVERThe configured Rancher server-url setting which the agent connects to
      --tokenCATTLE_TOKENToken that is needed to register the node in Rancher
      --ca-checksumCATTLE_CA_CHECKSUMThe SHA256 checksum of the configured Rancher cacerts setting to validate
      --node-nameCATTLE_NODE_NAMEOverride the hostname that is used to register the node (defaults to hostname -s)
      --labelCATTLE_NODE_LABELAdd node labels to the node. For multiple labels, pass additional --label options. (--label key=value)
      --taintsCATTLE_NODE_TAINTSAdd node taints to the node. For multiple taints, pass additional --taints options. (--taints key=value:effect)

      Role options​

      ParameterEnvironment variableDescription
      --all-rolesALL=trueApply all roles (etcd,controlplane,worker) to the node
      --etcdETCD=trueApply the role etcd to the node
      --controlplaneCONTROL=trueApply the role controlplane to the node
      --workerWORKER=trueApply the role worker to the node

      IP address options​

      ParameterEnvironment variableDescription
      --addressCATTLE_ADDRESSThe IP address the node will be registered with (defaults to the IP used to reach 8.8.8.8)
      --internal-addressCATTLE_INTERNAL_ADDRESSThe IP address used for inter-host communication on a private network

      Dynamic IP address options​

      For automation purposes, you can't have a specific IP address in a command as it has to be generic to be used for every node. For this, we have dynamic IP address options. They are used as a value to the existing IP address options. This is supported for --address and --internal-address.

      ValueExampleDescription
      Interface name--address eth0The first configured IP address will be retrieved from the given interface
      ipify--address ipifyValue retrieved from https://api.ipify.org will be used
      awslocal--address awslocalValue retrieved from http://169.254.169.254/latest/meta-data/local-ipv4 will be used
      awspublic--address awspublicValue retrieved from http://169.254.169.254/latest/meta-data/public-ipv4 will be used
      doprivate--address doprivateValue retrieved from http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address will be used
      dopublic--address dopublicValue retrieved from http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address will be used
      azprivate--address azprivateValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text will be used
      azpublic--address azpublicValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text will be used
      gceinternal--address gceinternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip will be used
      gceexternal--address gceexternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip will be used
      packetlocal--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/local-ipv4 will be used
      packetpublic--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/public-ipv4 will be used
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/configure-openldap/openldap-config-reference.html b/v2.0-v2.4/reference-guides/configure-openldap/openldap-config-reference.html index d42f2995e8b..60c40a1fe66 100644 --- a/v2.0-v2.4/reference-guides/configure-openldap/openldap-config-reference.html +++ b/v2.0-v2.4/reference-guides/configure-openldap/openldap-config-reference.html @@ -5,13 +5,13 @@ OpenLDAP Configuration Reference | Rancher Manager - +
      Version: v2.0-v2.4

      OpenLDAP Configuration Reference

      This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.

      For further details on configuring OpenLDAP, refer to the official documentation.

      Before you proceed with the configuration, please familiarize yourself with the concepts of External Authentication Configuration and Principal Users.

      Background: OpenLDAP Authentication Flow​

      1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
      2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
      3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
      4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.

      OpenLDAP Server Configuration

      You will need to enter the address, port, and protocol to connect to your OpenLDAP server. 389 is the standard port for insecure traffic, 636 for TLS traffic.

      Using TLS?

      If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

      If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

      OpenLDAP Server Parameters
      ParameterDescription
      HostnameSpecify the hostname or IP address of the OpenLDAP server
      PortSpecify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
      TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate.
      Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the server unreachable.
      Service Account Distinguished NameEnter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries.
      Service Account PasswordThe password for the service account.
      User Search BaseEnter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
      Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".

      User/Group Schema Configuration

      If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the Customize Schema section to match it.

      Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.

      If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

      User Schema Configuration​

      The table below details the parameters for the user schema configuration.

      User Schema Configuration Parameters
      ParameterDescription
      Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
      Username AttributeThe user attribute whose value is suitable as a display name.
      Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically uid.
      User Member AttributeThe user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of memberOf or isMemberOf.
      Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol.
      User Enabled AttributeIf the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty.
      Disabled Status BitmaskThis is the value for a disabled/locked user account. The parameter is ignored if User Enabled Attribute is empty.

      Group Schema Configuration​

      The table below details the parameters for the group schema configuration.

      Group Schema Configuration Parameters
      ParameterDescription
      Object ClassThe name of the object class used for group entries in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
      Name AttributeThe group attribute whose value is suitable for a display name.
      Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
      Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
      Search AttributeAttribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema Search Attribute.
      Group DN AttributeThe name of the group attribute whose format matches the values in the user's group membership attribute. See User Member Attribute.
      Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/installation-references/amazon-eks-permissions.html b/v2.0-v2.4/reference-guides/installation-references/amazon-eks-permissions.html index d1b36bdff19..b55f16a8e71 100644 --- a/v2.0-v2.4/reference-guides/installation-references/amazon-eks-permissions.html +++ b/v2.0-v2.4/reference-guides/installation-references/amazon-eks-permissions.html @@ -5,14 +5,14 @@ Creating an EKS Cluster | Rancher Manager - +
      Version: v2.0-v2.4

      Creating an EKS Cluster

      Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this documentation.

      Prerequisites in Amazon Web Services​

      Note Deploying to Amazon AWS will incur charges. For more information, refer to the EKS pricing page.

      To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate permissions. For details, refer to the official guide on Amazon EKS Prerequisites.

      Amazon VPC​

      You need to set up an Amazon VPC to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. For more information, refer to the Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster.

      IAM Policies​

      Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access.

      1. Create a user with programmatic access by following the steps here.

      2. Next, create an IAM policy that defines what this user has access to in your AWS account. It's important to only grant this user minimal access within your account. The minimum permissions required for an EKS cluster are listed here. Follow the steps here to create an IAM policy and attach it to your user.

      3. Finally, follow the steps here to create an access key and secret key for this user.

      Note: It's important to regularly rotate your access and secret keys. See this documentation for more information.

      For more detailed information on IAM policies for EKS, refer to the official documentation on Amazon EKS IAM Policies, Roles, and Permissions.

      Architecture​

      The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS.

      Managing Kubernetes Clusters through Rancher's Authentication Proxy

      Architecture

      Create the EKS Cluster​

      Use Rancher to set up and configure your Kubernetes cluster.

      1. From the Clusters page, click Add Cluster.

      2. Choose Amazon EKS.

      3. Enter a Cluster Name.

      4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

      5. Fill out the rest of the form. For help, refer to the configuration reference.

      6. Click Create.

      Result:

      Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

      You can access your cluster after its state is updated to Active.

      Active clusters are assigned two Projects:

      • Default, containing the default namespace
      • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

      EKS Cluster Configuration Reference​

      Account Access​

      Complete each drop-down and field using the information obtained for your IAM policy.

      SettingDescription
      RegionFrom the drop-down choose the geographical region in which to build your cluster.
      Access KeyEnter the access key that you created for your IAM policy.
      Secret KeyEnter the secret key that you created for your IAM policy.

      Service Role​

      Choose a service role.

      Service RoleDescription
      Standard: Rancher generated service roleIf you choose this role, Rancher automatically adds a service role for use with the cluster.
      Custom: Choose from your existing service rolesIf you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the Amazon documentation.

      Public IP for Worker Nodes​

      Your selection for this option determines what options are available for VPC & Subnet.

      OptionDescription
      YesWhen your cluster nodes are provisioned, they're assigned a both a private and public IP address.
      No: Private IPs onlyWhen your cluster nodes are provisioned, they're assigned only a private IP address.

      If you choose this option, you must also choose a VPC & Subnet that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane.

      VPC & Subnet​

      The available options depend on the public IP for worker nodes.

      OptionDescription
      Standard: Rancher generated VPC and SubnetWhile provisioning your cluster, Rancher generates a new VPC and Subnet.
      Custom: Choose from your existing VPC and SubnetsWhile provisioning your cluster, Rancher configures your nodes to use a VPC and Subnet that you've already created in AWS. If you choose this option, complete the remaining steps below.

      For more information, refer to the AWS documentation for Cluster VPC Considerations. Follow one of the sets of instructions below based on your selection from the previous step.

      If you choose to assign a public IP address to your cluster's worker nodes, you have the option of choosing between a VPC that's automatically generated by Rancher (i.e., Standard: Rancher generated VPC and Subnet), or a VPC that you've already created with AWS (i.e., Custom: Choose from your existing VPC and Subnets). Choose the option that best fits your use case.

      Click to expand

      If you're using Custom: Choose from your existing VPC and Subnets:

      (If you're using Standard, skip to the instance options.)

      1. Make sure Custom: Choose from your existing VPC and Subnets is selected.

      2. From the drop-down that displays, choose a VPC.

      3. Click Next: Select Subnets. Then choose one of the Subnets that displays.

      4. Click Next: Select Security Group.

      If your worker nodes have Private IPs only, you must also choose a VPC & Subnet that allow your instances to access the internet. This access is required so that your worker nodes can connect to the Kubernetes control plane.

      Click to expand

      Follow the steps below.

      Tip: When using only private IP addresses, you can provide your nodes internet access by creating a VPC constructed with two subnets, a private set and a public set. The private set should have its route tables configured to point toward a NAT in the public set. For more information on routing traffic from private subnets, please see the official AWS documentation.

      1. From the drop-down that displays, choose a VPC.

      2. Click Next: Select Subnets. Then choose one of the Subnets that displays.

      Security Group​

      Amazon Documentation:

      Instance Options​

      Instance type and size of your worker nodes affects how many IP addresses each worker node will have available. See this documentation for more information.

      OptionDescription
      Instance TypeChoose the hardware specs for the instance you're provisioning.
      Custom AMI OverrideIf you want to use a custom Amazon Machine Image (AMI), specify it here. By default, Rancher will use the EKS-optimized AMI for the EKS version that you chose.
      Desired ASG SizeThe number of instances that your cluster will provision.
      User DataCustom commands can to be passed to perform automated configuration tasks WARNING: Modifying this may cause your nodes to be unable to join the cluster. Note: Available as of v2.2.0

      Troubleshooting​

      If your changes were overwritten, it could be due to the way the cluster data is synced with EKS. Changes shouldn't be made to the cluster from another source, such as in the EKS console, and in Rancher within a five-minute span. For information on how this works and how to configure the refresh interval, refer to Syncing.

      If an unauthorized error is returned while attempting to modify or import the cluster and the cluster was not created with the role or user that your credentials belong to, refer to Security and Compliance.

      For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this documentation.

      AWS Service Events​

      To find information on any AWS Service events, please see this page.

      Security and Compliance​

      By default only the IAM user or role that created a cluster has access to it. Attempting to access the cluster with any other user or role without additional configuration will lead to an error. In Rancher, this means using a credential that maps to a user or role that was not used to create the cluster will cause an unauthorized error. For example, an EKSCtl cluster will not be imported in Rancher unless the credentials used to import the cluster match the role or user used by EKSCtl. Additional users and roles can be authorized to access a cluster by being added to the aws-auth configmap in the kube-system namespace. For a more in-depth explanation and detailed instructions, please see this documentation.

      For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this documentation.

      Tutorial​

      This tutorial on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB.

      Minimum EKS Permissions​

      Documented here is a minimum set of permissions necessary to use all functionality of the EKS driver in Rancher. Additional permissions are required for Rancher to provision the Service Role and VPC resources. Optionally these resources can be created before the cluster creation and will be selectable when defining the cluster configuration.

      ResourceDescription
      Service RoleThe service role provides Kubernetes the permissions it requires to manage resources on your behalf. Rancher can create the service role with the following Service Role Permissions.
      VPCProvides isolated network resources utilised by EKS and worker nodes. Rancher can create the VPC resources with the following VPC Permissions.

      Resource targeting uses * as the ARN of many of the resources created cannot be known before creating the EKS cluster in Rancher.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "EC2Permisssions",
                  "Effect": "Allow",
                  "Action": [
                      "ec2:RunInstances",
                      "ec2:RevokeSecurityGroupIngress",
                      "ec2:RevokeSecurityGroupEgress",
                      "ec2:DescribeVpcs",
                      "ec2:DescribeTags",
                      "ec2:DescribeSubnets",
                      "ec2:DescribeSecurityGroups",
                      "ec2:DescribeRouteTables",
                      "ec2:DescribeLaunchTemplateVersions",
                      "ec2:DescribeLaunchTemplates",
                      "ec2:DescribeKeyPairs",
                      "ec2:DescribeInternetGateways",
                      "ec2:DescribeImages",
                      "ec2:DescribeAvailabilityZones",
                      "ec2:DescribeAccountAttributes",
                      "ec2:DeleteTags",
                      "ec2:DeleteSecurityGroup",
                      "ec2:DeleteKeyPair",
                      "ec2:CreateTags",
                      "ec2:CreateSecurityGroup",
                      "ec2:CreateLaunchTemplateVersion",
                      "ec2:CreateLaunchTemplate",
                      "ec2:CreateKeyPair",
                      "ec2:AuthorizeSecurityGroupIngress",
                      "ec2:AuthorizeSecurityGroupEgress"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "CloudFormationPermisssions",
                  "Effect": "Allow",
                  "Action": [
                      "cloudformation:ListStacks",
                      "cloudformation:ListStackResources",
                      "cloudformation:DescribeStacks",
                      "cloudformation:DescribeStackResources",
                      "cloudformation:DescribeStackResource",
                      "cloudformation:DeleteStack",
                      "cloudformation:CreateStackSet",
                      "cloudformation:CreateStack"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "IAMPermissions",
                  "Effect": "Allow",
                  "Action": [
                      "iam:PassRole",
                      "iam:ListRoles",
                      "iam:ListRoleTags",
                      "iam:ListInstanceProfilesForRole",
                      "iam:ListInstanceProfiles",
                      "iam:ListAttachedRolePolicies",
                      "iam:GetRole",
                      "iam:GetInstanceProfile",
                      "iam:DetachRolePolicy",
                      "iam:DeleteRole",
                      "iam:CreateRole",
                      "iam:AttachRolePolicy"
                  ],
                  "Resource": "*"
              },
              {
                  "Sid": "KMSPermisssions",
                  "Effect": "Allow",
                  "Action": "kms:ListKeys",
                  "Resource": "*"
              },
              {
                  "Sid": "EKSPermisssions",
                  "Effect": "Allow",
                  "Action": [
                      "eks:UpdateNodegroupVersion",
                      "eks:UpdateNodegroupConfig",
                      "eks:UpdateClusterVersion",
                      "eks:UpdateClusterConfig",
                      "eks:UntagResource",
                      "eks:TagResource",
                      "eks:ListUpdates",
                      "eks:ListTagsForResource",
                      "eks:ListNodegroups",
                      "eks:ListFargateProfiles",
                      "eks:ListClusters",
                      "eks:DescribeUpdate",
                      "eks:DescribeNodegroup",
                      "eks:DescribeFargateProfile",
                      "eks:DescribeCluster",
                      "eks:DeleteNodegroup",
                      "eks:DeleteFargateProfile",
                      "eks:DeleteCluster",
                      "eks:CreateNodegroup",
                      "eks:CreateFargateProfile",
                      "eks:CreateCluster"
                  ],
                  "Resource": "*"
              }
          ]
      }

      Service Role Permissions​

      Rancher will create a service role with the following trust policy:

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Principal": {
              "Service": "eks.amazonaws.com"
            },
            "Effect": "Allow",
            "Sid": ""
          }
        ]
      }

      This role will also have two role policy attachments with the following policies ARNs:

      arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
      arn:aws:iam::aws:policy/AmazonEKSServicePolicy

      Permissions required for Rancher to create service role on users behalf during the EKS cluster creation process.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "IAMPermisssions",
            "Effect": "Allow",
            "Action": [
              "iam:AddRoleToInstanceProfile",
              "iam:AttachRolePolicy",
              "iam:CreateInstanceProfile",
              "iam:CreateRole",
              "iam:CreateServiceLinkedRole",
              "iam:DeleteInstanceProfile",
              "iam:DeleteRole",
              "iam:DetachRolePolicy",
              "iam:GetInstanceProfile",
              "iam:GetRole",
              "iam:ListAttachedRolePolicies",
              "iam:ListInstanceProfiles",
              "iam:ListInstanceProfilesForRole",
              "iam:ListRoles",
              "iam:ListRoleTags",
              "iam:PassRole",
              "iam:RemoveRoleFromInstanceProfile"
            ],
            "Resource": "*"
          }
        ]
      }

      VPC Permissions​

      Permissions required for Rancher to create VPC and associated resources.

      {
        "Sid": "VPCPermissions",
        "Effect": "Allow",
        "Action": [
           "ec2:ReplaceRoute",
           "ec2:ModifyVpcAttribute",
           "ec2:ModifySubnetAttribute",
           "ec2:DisassociateRouteTable",
           "ec2:DetachInternetGateway",
           "ec2:DescribeVpcs",
           "ec2:DeleteVpc",
           "ec2:DeleteTags",
           "ec2:DeleteSubnet",
           "ec2:DeleteRouteTable",
           "ec2:DeleteRoute",
           "ec2:DeleteInternetGateway",
           "ec2:CreateVpc",
           "ec2:CreateSubnet",
           "ec2:CreateSecurityGroup",
           "ec2:CreateRouteTable",
           "ec2:CreateRoute",
           "ec2:CreateInternetGateway",
           "ec2:AttachInternetGateway",
           "ec2:AssociateRouteTable"
        ],
        "Resource": "*"
      }
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/installation-references/feature-flags.html b/v2.0-v2.4/reference-guides/installation-references/feature-flags.html index 6d5763940cb..f7d7d740b0b 100644 --- a/v2.0-v2.4/reference-guides/installation-references/feature-flags.html +++ b/v2.0-v2.4/reference-guides/installation-references/feature-flags.html @@ -5,13 +5,13 @@ Feature Flags | Rancher Manager - +
      Version: v2.0-v2.4

      Feature Flags

      Feature flags were introduced to allow you to try experimental features that are not enabled by default.

      To learn about feature values and how to enable features, refer here.

      note

      As of v2.4.0, there are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.

      The following is a list of the feature flags available in Rancher:

      • dashboard: This feature enables the new experimental UI that has a new look and feel. The dashboard also leverages a new API in Rancher which allows the UI to access the default Kubernetes resources without any intervention from Rancher.
      • istio-virtual-service-ui: This feature enables a UI to create, read, update, and delete Istio virtual services and destination rules, which are traffic management features of Istio.
      • proxy: This feature enables Rancher to use a new simplified code base for the proxy, which can help enhance performance and security. The proxy feature is known to have issues with Helm deployments, which prevents any catalog applications to be deployed which includes Rancher's tools like monitoring, logging, Istio, etc.
      • unsupported-storage-drivers: This feature allows unsupported storage drivers. In other words, it enables types for storage providers and provisioners that are not enabled by default.

      The below table shows the availability and default value for feature flags in Rancher:

      Feature Flag NameDefault ValueStatusAvailable as ofRancher Restart Required?
      dashboardtrueExperimentalv2.4.0x
      istio-virtual-service-uifalseExperimentalv2.3.0
      istio-virtual-service-uitrueGAv2.3.2
      proxyfalseExperimentalv2.4.0
      unsupported-storage-driversfalseExperimentalv2.3.0
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/installation-references/helm-chart-options.html b/v2.0-v2.4/reference-guides/installation-references/helm-chart-options.html index 8446417d292..a6e504bf978 100644 --- a/v2.0-v2.4/reference-guides/installation-references/helm-chart-options.html +++ b/v2.0-v2.4/reference-guides/installation-references/helm-chart-options.html @@ -5,13 +5,13 @@ Rancher Helm Chart Options | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher Helm Chart Options

      This page is a configuration reference for the Rancher Helm chart.

      For help choosing a Helm chart version, refer to this page.

      For information on enabling experimental features, refer to this page.

      Common Options​

      OptionDefault ValueDescription
      hostname" "string - the Fully Qualified Domain Name for your Rancher Server
      ingress.tls.source"rancher"string - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret"
      letsEncrypt.email" "string - Your email address
      letsEncrypt.environment"production"string - Valid options: "staging, production"
      privateCAfalsebool - Set to true if your cert is signed by a private CA

      Advanced Options​

      OptionDefault ValueDescription
      additionalTrustedCAsfalsebool - See Additional Trusted CAs
      addLocal"true"string - Have Rancher detect and import the "local" Rancher server cluster. Note: This option is no longer available in v2.5.0. In v2.5.0, the restrictedAdmin option is used to prevent users from modifying the local cluster.
      antiAffinity"preferred"string - AntiAffinity rule for Rancher pods - "preferred, required"
      auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
      auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
      auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
      auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
      auditLog.maxBackup1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
      auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
      busyboxImage"busybox"string - Image location for busybox image used to collect audit logs Note: Available as of v2.2.0
      certmanager.version""string - set cert-manager compatibility
      debugfalsebool - set debug flag on rancher server
      extraEnv[]list - set additional environment variables for Rancher Note: Available as of v2.2.0
      imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
      ingress.configurationSnippet""string - Add additional Nginx configuration. Can be used for proxy configuration. Note: Available as of v2.0.15, v2.1.10 and v2.2.4
      ingress.extraAnnotations{}map - additional annotations to customize the ingress
      letsEncrypt.ingress.class""string - optional ingress class for the cert-manager acmesolver ingress that responds to the Let's Encrypt ACME challenges. Options: traefik, nginx.
      noProxy"127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local,cattle-system.svc"string - comma separated list of hostnames or ip address not to use the proxy
      proxy""string - HTTP[S] proxy server for Rancher
      rancherImage"rancher/rancher"string - rancher image source
      rancherImagePullPolicy"IfNotPresent"string - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent"
      rancherImageTagsame as chart versionstring - rancher/rancher image tag
      replicas3int - Number of replicas of Rancher pods
      resources{}map - rancher pod resource requests & limits
      systemDefaultRegistry""string - private registry to be used for all system Docker images, e.g., registry.example.com
      tls"ingress"string - See External TLS Termination for details. - "ingress, external"
      useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.

      API Audit Log​

      Enabling the API Audit Log.

      You can collect this log as you would any container log. Enable the Logging service under Rancher Tools for the System Project on the Rancher server cluster.

      --set auditLog.level=1

      By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (rancher-audit-log) will stream the log to stdout. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the hostPath, maxAge, maxBackups, and maxSize options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable the Logging service under Rancher Tools for the Rancher server cluster or System Project.

      Set the auditLog.destination to hostPath to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to hostPath you may want to adjust the other auditLog parameters for log rotation.

      Setting Extra Environment Variables​

      You can set extra environment variables for Rancher server using extraEnv. This list uses the same name and value keys as the container manifest definitions. Remember to quote the values.

      --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
      --set 'extraEnv[0].value=1.0'

      TLS Settings​

      To set a different TLS configuration, you can use the CATTLE_TLS_MIN_VERSION and CATTLE_TLS_CIPHERS environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:

      --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
      --set 'extraEnv[0].value=1.0'

      See TLS settings for more information and options.

      Import local Cluster​

      By default Rancher server will detect and import the local cluster it's running on. User with access to the local cluster will essentially have "root" access to all the clusters managed by Rancher server.

      Important if you are considering upgrading to Rancher v2.5: If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner. In Rancher v2.5, the restrictedAdmin option is used to prevent users from modifying the local cluster.

      If this is a concern in your environment you can set this option to "false" on your initial install.

      This option is only effective on the initial Rancher install. See Issue 16522 for more information.

      --set addLocal="false"

      Customizing your Ingress​

      To customize or use a different ingress with Rancher server you can set your own Ingress annotations.

      Example on setting a custom certificate issuer:

      --set ingress.extraAnnotations.'cert-manager\.io/cluster-issuer'=issuer-name

      Example on setting a static proxy header with ingress.configurationSnippet. This value is parsed like a template so variables can be used.

      --set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};'

      HTTP Proxy​

      Rancher requires internet access for some functionality (helm charts). Use proxy to set your proxy server.

      Add your IP exceptions to the noProxy list. Make sure you add the Pod cluster IP range (default: 10.42.0.0/16), Service cluster IP range (default: 10.43.0.0/16), the internal cluster domains (default: .svc,.cluster.local) and any worker cluster controlplane nodes. Rancher supports CIDR notation ranges in this list.

      --set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
      --set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local"

      Additional Trusted CAs​

      If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.

      --set additionalTrustedCAs=true

      Once the Rancher deployment is created, copy your CA certs in pem format into a file named ca-additional.pem and use kubectl to create the tls-ca-additional secret in the cattle-system namespace.

      kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem=./ca-additional.pem

      Private Registry and Air Gap Installs​

      For details on installing Rancher with a private registry, see:

      External TLS Termination

      We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

      You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the --set tls=external option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.

      Note: If you are using a Private CA signed certificate, add --set privateCA=true and see Adding TLS Secrets - Using a Private CA Signed Certificate to add the CA cert for Rancher.

      Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

      Configuring Ingress for External TLS when Using NGINX v0.25​

      In NGINX v0.25, the behavior of NGINX has changed regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the cluster.yml to enable the use-forwarded-headers option for ingress:

      ingress:
        provider: nginx
        options:
          use-forwarded-headers: 'true'

      Required Headers​

      • Host
      • X-Forwarded-Proto
      • X-Forwarded-Port
      • X-Forwarded-For
      • Read Timeout: 1800 seconds
      • Write Timeout: 1800 seconds
      • Connect Timeout: 30 seconds

      Health Checks​

      Rancher will respond 200 to health checks on the /healthz endpoint.

      Example NGINX config​

      This NGINX configuration is tested on NGINX 1.14.

      Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

      • Replace IP_NODE1, IP_NODE2 and IP_NODE3 with the IP addresses of the nodes in your cluster.
      • Replace both occurrences of FQDN to the DNS name for Rancher.
      • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
      worker_processes 4;
      worker_rlimit_nofile 40000;

      events {
          worker_connections 8192;
      }

      http {
          upstream rancher {
              server IP_NODE_1:80;
              server IP_NODE_2:80;
              server IP_NODE_3:80;
          }

          map $http_upgrade $connection_upgrade {
              default Upgrade;
              ''      close;
          }

          server {
              listen 443 ssl http2;
              server_name FQDN;
              ssl_certificate /certs/fullchain.pem;
              ssl_certificate_key /certs/privkey.pem;

              location / {
                  proxy_set_header Host $host;
                  proxy_set_header X-Forwarded-Proto $scheme;
                  proxy_set_header X-Forwarded-Port $server_port;
                  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                  proxy_pass http://rancher;
                  proxy_http_version 1.1;
                  proxy_set_header Upgrade $http_upgrade;
                  proxy_set_header Connection $connection_upgrade;
                  # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                  proxy_read_timeout 900s;
                  proxy_buffering off;
              }
          }

          server {
              listen 80;
              server_name FQDN;
              return 301 https://$server_name$request_uri;
          }
      }
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/installation-references/tls-settings.html b/v2.0-v2.4/reference-guides/installation-references/tls-settings.html index ca92bb17686..45aab0a4300 100644 --- a/v2.0-v2.4/reference-guides/installation-references/tls-settings.html +++ b/v2.0-v2.4/reference-guides/installation-references/tls-settings.html @@ -5,13 +5,13 @@ TLS Settings | Rancher Manager - +
      Version: v2.0-v2.4

      TLS Settings

      In Rancher v2.1.7, the default TLS configuration changed to only accept TLS 1.2 and secure TLS cipher suites. TLS 1.3 and TLS 1.3 exclusive cipher suites are not supported.

      Configuring TLS settings

      The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.

      TLS Environment Variables

      ParameterDescriptionDefaultAvailable options
      CATTLE_TLS_MIN_VERSIONMinimum TLS version1.21.0, 1.1, 1.2
      CATTLE_TLS_CIPHERSAllowed TLS cipher suitesTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
      TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
      TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
      TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305      		See Golang tls constants

      Legacy configuration

      If you need to configure TLS the same way as it was before Rancher v2.1.7, please use the following settings:

      ParameterLegacy value
      CATTLE_TLS_MIN_VERSION1.0
      CATTLE_TLS_CIPHERSTLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
      TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
      TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
      TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
      TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
      TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
      TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
      TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
      TLS_RSA_WITH_AES_128_GCM_SHA256,
      TLS_RSA_WITH_AES_256_GCM_SHA384,
      TLS_RSA_WITH_AES_128_CBC_SHA,
      TLS_RSA_WITH_AES_256_CBC_SHA,
      TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
      TLS_RSA_WITH_3DES_EDE_CBC_SHA
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/kubernetes-concepts.html b/v2.0-v2.4/reference-guides/kubernetes-concepts.html index 1d6a24e5973..25602045a94 100644 --- a/v2.0-v2.4/reference-guides/kubernetes-concepts.html +++ b/v2.0-v2.4/reference-guides/kubernetes-concepts.html @@ -5,13 +5,13 @@ Kubernetes Concepts | Rancher Manager - +
      Version: v2.0-v2.4

      Kubernetes Concepts

      This page explains concepts related to Kubernetes that are important for understanding how Rancher works. The descriptions below provide a simplified interview of Kubernetes components. For more details, refer to the official documentation on Kubernetes components.

      About Docker​

      Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. Docker Hub is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes.

      Note: Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes.

      About Kubernetes​

      Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management.

      What is a Kubernetes Cluster?​

      A cluster is a group of computers that work together as a single system.

      A Kubernetes Cluster is a cluster that uses the Kubernetes container-orchestration system to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations.

      Roles for Nodes in Kubernetes Clusters​

      Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: etcd nodes, control plane nodes, and worker nodes.

      A Kubernetes cluster consists of at least one etcd, controlplane, and worker node.

      etcd Nodes​

      Rancher uses etcd as a data store in both single node and high-availability installations. In Kubernetes, etcd is also a role for nodes that store the cluster state.

      The state of a Kubernetes cluster is maintained in etcd. The etcd nodes run the etcd database.

      The etcd database component is a distributed key-value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. It is recommended to run etcd on multiple nodes so that there's always a backup available for failover.

      Although you can run etcd on just one node, etcd requires a majority of nodes, a quorum, to agree on updates to the cluster state. The cluster should always contain enough healthy etcd nodes to form a quorum. For a cluster with n members, a quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for a quorum.

      Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters.

      Controlplane Nodes​

      Controlplane nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although three or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles.

      Worker Nodes​

      Each worker node runs the following:

      • Kubelets: An agent that monitors the state of the node, ensuring your containers are healthy.
      • Workloads: The containers and pods that hold your apps, as well as other types of deployments.

      Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads.

      About Helm​

      For high-availability installations of Rancher, Helm is the tool used to install Rancher on a Kubernetes cluster.

      Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

      For more information on service accounts and cluster role binding, refer to the Kubernetes documentation.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/concepts.html b/v2.0-v2.4/reference-guides/pipelines/concepts.html index 41f1dbd5d31..64bea2991cb 100644 --- a/v2.0-v2.4/reference-guides/pipelines/concepts.html +++ b/v2.0-v2.4/reference-guides/pipelines/concepts.html @@ -5,13 +5,13 @@ Concepts | Rancher Manager - +
      Version: v2.0-v2.4

      Concepts

      The purpose of this page is to explain common concepts and terminology related to pipelines.

      • Pipeline:

        A pipeline is a software delivery process that is broken into different stages and steps. Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. A pipeline is based on a specific repository. It defines the process to build, test, and deploy your code. Rancher uses the pipeline as code model. Pipeline configuration is represented as a pipeline file in the source code repository, using the file name .rancher-pipeline.yml or .rancher-pipeline.yaml.

      • Stages:

        A pipeline stage consists of multiple steps. Stages are executed in the order defined in the pipeline file. The steps in a stage are executed concurrently. A stage starts when all steps in the former stage finish without failure.

      • Steps:

        A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than 0. If a step exits with this failure code, the entire pipeline fails and terminates.

      • Workspace:

        The workspace is the working directory shared by all pipeline steps. In the beginning of a pipeline, source code is checked out to the workspace. The command for every step bootstraps in the workspace. During a pipeline execution, the artifacts from a previous step will be available in future steps. The working directory is an ephemeral volume and will be cleaned out with the executor pod when a pipeline execution is finished.

      Typically, pipeline stages include:

      • Build:

        Each time code is checked into your repository, the pipeline automatically clones the repo and builds a new iteration of your software. Throughout this process, the software is typically reviewed by automated tests.

      • Publish:

        After the build is completed, either a Docker image is built and published to a Docker registry or a catalog template is published.

      • Deploy:

        After the artifacts are published, you would release your application so users could start using the updated product.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/configure-persistent-data.html b/v2.0-v2.4/reference-guides/pipelines/configure-persistent-data.html index 82d4229cd4a..d4a7c24a132 100644 --- a/v2.0-v2.4/reference-guides/pipelines/configure-persistent-data.html +++ b/v2.0-v2.4/reference-guides/pipelines/configure-persistent-data.html @@ -5,13 +5,13 @@ Configuring Persistent Data for Pipeline Components | Rancher Manager - +
      Version: v2.0-v2.4

      Configuring Persistent Data for Pipeline Components

      The pipelines' internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

      This section assumes that you understand how persistent storage works in Kubernetes. For more information, refer to the section on how storage works.

      Prerequisites (for both parts A and B):

      Persistent volumes must be available for the cluster.

      A. Configuring Persistent Data for Docker Registry​

      1. From the project that you're configuring a pipeline for, and click Resources > Workloads. In versions before v2.3.0, select the Workloads tab.

      2. Find the docker-registry workload and select ⋮ > Edit.

      3. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

        • Add Volume > Add a new persistent volume (claim)
        • Add Volume > Use an existing persistent volume (claim)

      4. Complete the form that displays to choose a persistent volume for the internal Docker registry.

        1. Enter a Name for the volume claim.
        2. Select a volume claim Source:
          • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
          • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
        3. From the Customize section, choose the read/write access for the volume.
        4. Click Define.

      5. From the Mount Point field, enter /var/lib/registry, which is the data storage path inside the Docker registry container.

      6. Click Upgrade.

      B. Configuring Persistent Data for Minio​

      1. From the project view, click Resources > Workloads. (In versions before v2.3.0, click the Workloads tab.) Find the minio workload and select ⋮ > Edit.

      2. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

        • Add Volume > Add a new persistent volume (claim)
        • Add Volume > Use an existing persistent volume (claim)

      3. Complete the form that displays to choose a persistent volume for the internal Docker registry.

        1. Enter a Name for the volume claim.
        2. Select a volume claim Source:
          • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
          • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
        3. From the Customize section, choose the read/write access for the volume.
        4. Click Define.

      4. From the Mount Point field, enter /data, which is the data storage path inside the Minio container.

      5. Click Upgrade.

      Result: Persistent storage is configured for your pipeline components.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/example-repositories.html b/v2.0-v2.4/reference-guides/pipelines/example-repositories.html index 209e7831554..f5b42628f75 100644 --- a/v2.0-v2.4/reference-guides/pipelines/example-repositories.html +++ b/v2.0-v2.4/reference-guides/pipelines/example-repositories.html @@ -5,13 +5,13 @@ Example Repositories | Rancher Manager - +
      Version: v2.0-v2.4

      Example Repositories

      Rancher ships with several example repositories that you can use to familiarize yourself with pipelines. We recommend configuring and testing the example repository that most resembles your environment before using pipelines with your own repositories in a production environment. Use this example repository as a sandbox for repo configuration, build demonstration, etc. Rancher includes example repositories for:

      • Go
      • Maven
      • php

      Note: The example repositories are only available if you have not configured a version control provider.

      To start using these example repositories,

      1. Enable the example repositories
      2. View the example pipeline
      3. Run the example pipeline

      1. Enable the Example Repositories​

      By default, the example pipeline repositories are disabled. Enable one (or more) to test out the pipeline feature and see how it works.

      1. From the Global view, navigate to the project that you want to test out pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Click Configure Repositories.

        Step Result: A list of example repositories displays.

        Note: Example repositories only display if you haven't fetched your own repos.

      4. Click Enable for one of the example repos (e.g., https://github.com/rancher/pipeline-example-go.git). Then click Done.

      Results:

      • The example repository is enabled to work with a pipeline is available in the Pipeline tab.

      • The following workloads are deployed to a new namespace:

        • docker-registry
        • jenkins
        • minio

      2. View the Example Pipeline​

      After enabling an example repository, review the pipeline to see how it is set up.

      1. From the Global view, navigate to the project that you want to test out pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Find the example repository, select the vertical ⋮. There are two ways to view the pipeline:

      • Rancher UI: Click on Edit Config to view the stages and steps of the pipeline.
      • YAML: Click on View/Edit YAML to view the ./rancher-pipeline.yml file.

      3. Run the Example Pipeline​

      After enabling an example repository, run the pipeline to see how it works.

      1. From the Global view, navigate to the project that you want to test out pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. Find the example repository, select the vertical ⋮ > Run.

        Note: When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components.

      Result: The pipeline runs. You can see the results in the logs.

      What's Next?​

      For detailed information about setting up your own pipeline for your repository, configure a version control provider, enable a repository and finally configure your pipeline.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/example-yaml.html b/v2.0-v2.4/reference-guides/pipelines/example-yaml.html index 056aaf4a50c..d078b439b17 100644 --- a/v2.0-v2.4/reference-guides/pipelines/example-yaml.html +++ b/v2.0-v2.4/reference-guides/pipelines/example-yaml.html @@ -5,13 +5,13 @@ Example YAML File | Rancher Manager - +
      Version: v2.0-v2.4

      Example YAML File

      Pipelines can be configured either through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml.

      In the pipeline configuration reference, we provide examples of how to configure each feature using the Rancher UI or using YAML configuration.

      Below is a full example rancher-pipeline.yml for those who want to jump right in.

      # example
      stages:
        - name: Build something
          # Conditions for stages
          when:
            branch: master
            event: [ push, pull_request ]
          # Multiple steps run concurrently
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: echo ${FIRST_KEY} && echo ${ALIAS_ENV}
            # Set environment variables in container for the step
            env:
              FIRST_KEY: VALUE
              SECOND_KEY: VALUE2
            # Set environment variables from project secrets
            envFrom:
            - sourceName: my-secret
              sourceKey: secret-key
              targetKey: ALIAS_ENV
          - runScriptConfig:
              image: busybox
              shellScript: date -R
            # Conditions for steps
            when:
              branch: [ master, dev ]
              event: push
        - name: Publish my image
          steps:
          - publishImageConfig:
              dockerfilePath: ./Dockerfile
              buildContext: .
              tag: rancher/rancher:v2.0.0
              # Optionally push to remote registry
              pushRemote: true
              registry: reg.example.com
        - name: Deploy some workloads
          steps:
          - applyYamlConfig:
              path: ./deployment.yaml
      # branch conditions for the pipeline
      branch:
        include: [ master, feature/*]
        exclude: [ dev ]
      # timeout in minutes
      timeout: 30
      notification:
        recipients:
        - # Recipient
          recipient: "#mychannel"
          # ID of Notifier
          notifier: "c-wdcsr:n-c9pg7"
        - recipient: "test@example.com"
          notifier: "c-wdcsr:n-lkrhd"
        # Select which statuses you want the notification to be sent
        condition: ["Failed", "Success", "Changed"]
        # Ability to override the default message (Optional)
        message: "my-message"
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/pipeline-configuration.html b/v2.0-v2.4/reference-guides/pipelines/pipeline-configuration.html index 3f6e8562b28..65d7e6003f3 100644 --- a/v2.0-v2.4/reference-guides/pipelines/pipeline-configuration.html +++ b/v2.0-v2.4/reference-guides/pipelines/pipeline-configuration.html @@ -5,13 +5,13 @@ Pipeline Configuration Reference | Rancher Manager - +
      Version: v2.0-v2.4

      Pipeline Configuration Reference

      In this section, you'll learn how to configure pipelines.

      Step Types​

      Within each stage, you can add as many steps as you'd like. When there are multiple steps in one stage, they run concurrently.

      Step types include:

      Configuring Steps By UI​

      If you haven't added any stages, click Configure pipeline for this branch to configure the pipeline through the UI.

      1. Add stages to your pipeline execution by clicking Add Stage.

        1. Enter a Name for each stage of your pipeline.
        2. For each stage, you can configure trigger rules by clicking on Show Advanced Options. Note: this can always be updated at a later time.

      2. After you've created a stage, start adding steps by clicking Add a Step. You can add multiple steps to each stage.

      Configuring Steps by YAML​

      For each stage, you can add multiple steps. Read more about each step type and the advanced options to get all the details on how to configure the YAML. This is only a small example of how to have multiple stages with a singular step in each stage.

      # example
      stages:
        - name: Build something
          # Conditions for stages
          when:
            branch: master
            event: [ push, pull_request ]
          # Multiple steps run concurrently
          steps:
            - runScriptConfig:
                image: busybox
                shellScript: date -R
        - name: Publish my image
          steps:
          - publishImageConfig:
              dockerfilePath: ./Dockerfile
              buildContext: .
              tag: rancher/rancher:v2.0.0
              # Optionally push to remote registry
              pushRemote: true
              registry: reg.example.com

      Step Type: Run Script​

      The Run Script step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience, you can use variables to refer to metadata of a pipeline execution. Please refer to the pipeline variable substitution reference for the list of available variables.

      Configuring Script by UI​

      1. From the Step Type drop-down, choose Run Script and fill in the form.

      2. Click Add.

      Configuring Script by YAML​

      # example
      stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: golang
            shellScript: go build

      Step Type: Build and Publish Images​

      Available as of Rancher v2.1.0

      The Build and Publish Image step builds and publishes a Docker image. This process requires a Dockerfile in your source code's repository to complete successfully.

      The option to publish an image to an insecure registry is not exposed in the UI, but you can specify an environment variable in the YAML that allows you to publish an image insecurely.

      Configuring Building and Publishing Images by UI​

      1. From the Step Type drop-down, choose Build and Publish.

      2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

        FieldDescription
        Dockerfile PathThe relative path to the Dockerfile in the source code repo. By default, this path is ./Dockerfile, which assumes the Dockerfile is in the root directory. You can set it to other paths in different use cases (./path/to/myDockerfile for example).
        Image NameThe image name in name:tag format. The registry address is not required. For example, to build example.com/repo/my-image:dev, enter repo/my-image:dev.
        Push image to remote repositoryAn option to set the registry that publishes the image that's built. To use this option, enable it and choose a registry from the drop-down. If this option is disabled, the image is pushed to the internal registry.
        Build Context

        (Show advanced options)        		By default, the root directory of the source code (.). For more details, see the Docker build command documentation.

      Configuring Building and Publishing Images by YAML​

      You can use specific arguments for Docker daemon and the build. They are not exposed in the UI, but they are available in pipeline YAML format, as indicated in the example below. Available environment variables include:

      Variable NameDescription
      PLUGIN_DRY_RUNDisable docker push
      PLUGIN_DEBUGDocker daemon executes in debug mode
      PLUGIN_MIRRORDocker daemon registry mirror
      PLUGIN_INSECUREDocker daemon allows insecure registries
      PLUGIN_BUILD_ARGSDocker build args, a comma separated list

      # This example shows an environment variable being used
      # in the Publish Image step. This variable allows you to
      # publish an image to an insecure registry:

      stages:
      - name: Publish Image
        steps:
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: repo/app:v1
            pushRemote: true
            registry: example.com
          env:
            PLUGIN_INSECURE: "true"

      Step Type: Publish Catalog Template​

      Available as of v2.2.0

      The Publish Catalog Template step publishes a version of a catalog app template (i.e. Helm chart) to a git hosted chart repository. It generates a git commit and pushes it to your chart repository. This process requires a chart folder in your source code's repository and a pre-configured secret in the dedicated pipeline namespace to complete successfully. Any variables in the pipeline variable substitution reference is supported for any file in the chart folder.

      Configuring Publishing a Catalog Template by UI​

      1. From the Step Type drop-down, choose Publish Catalog Template.

      2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

        FieldDescription
        Chart FolderThe relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
        Catalog Template NameThe name of the template. For example, wordpress.
        Catalog Template VersionThe version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
        ProtocolYou can choose to publish via HTTP(S) or SSH protocol.
        SecretThe secret that stores your Git credentials. You need to create a secret in dedicated pipeline namespace in the project before adding this step. If you use HTTP(S) protocol, store Git username and password in USERNAME and PASSWORD key of the secret. If you use SSH protocol, store Git deploy key in DEPLOY_KEY key of the secret. After the secret is created, select it in this option.
        Git URLThe Git URL of the chart repository that the template will be published to.
        Git BranchThe Git branch of the chart repository that the template will be published to.
        Author NameThe author name used in the commit message.
        Author EmailThe author email used in the commit message.

      Configuring Publishing a Catalog Template by YAML​

      You can add Publish Catalog Template steps directly in the .rancher-pipeline.yml file.

      Under the steps section, add a step with publishCatalogConfig. You will provide the following information:

      • Path: The relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
      • CatalogTemplate: The name of the template.
      • Version: The version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
      • GitUrl: The git URL of the chart repository that the template will be published to.
      • GitBranch: The git branch of the chart repository that the template will be published to.
      • GitAuthor: The author name used in the commit message.
      • GitEmail: The author email used in the commit message.
      • Credentials: You should provide Git credentials by referencing secrets in dedicated pipeline namespace. If you publish via SSH protocol, inject your deploy key to the DEPLOY_KEY environment variable. If you publish via HTTP(S) protocol, inject your username and password to USERNAME and PASSWORD environment variables.
      # example
      stages:
      - name: Publish Wordpress Template
        steps:
        - publishCatalogConfig:
            path: ./charts/wordpress/latest
            catalogTemplate: wordpress
            version: ${CICD_GIT_TAG}
            gitUrl: git@github.com:myrepo/charts.git
            gitBranch: master
            gitAuthor: example-user
            gitEmail: user@example.com
          envFrom:
          - sourceName: publish-keys
            sourceKey: DEPLOY_KEY

      Step Type: Deploy YAML​

      This step deploys arbitrary Kubernetes resources to the project. This deployment requires a Kubernetes manifest file to be present in the source code repository. Pipeline variable substitution is supported in the manifest file. You can view an example file at GitHub. Please refer to the pipeline variable substitution reference for the list of available variables.

      Configure Deploying YAML by UI​

      1. From the Step Type drop-down, choose Deploy YAML and fill in the form.

      2. Enter the YAML Path, which is the path to the manifest file in the source code.

      3. Click Add.

      Configure Deploying YAML by YAML​

      # example
      stages:
      - name: Deploy
        steps:
        - applyYamlConfig:
            path: ./deployment.yaml

      Step Type :Deploy Catalog App​

      Available as of v2.2.0

      The Deploy Catalog App step deploys a catalog app in the project. It will install a new app if it is not present, or upgrade an existing one.

      Configure Deploying Catalog App by UI​

      1. From the Step Type drop-down, choose Deploy Catalog App.

      2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

        FieldDescription
        CatalogThe catalog from which the app template will be used.
        Template NameThe name of the app template. For example, wordpress.
        Template VersionThe version of the app template you want to deploy.
        NamespaceThe target namespace where you want to deploy the app.
        App NameThe name of the app you want to deploy.
        AnswersKey-value pairs of answers used to deploy the app.

      Configure Deploying Catalog App by YAML​

      You can add Deploy Catalog App steps directly in the .rancher-pipeline.yml file.

      Under the steps section, add a step with applyAppConfig. You will provide the following information:

      • CatalogTemplate: The ID of the template. This can be found by clicking Launch app and selecting View details for the app. It is the last part of the URL.
      • Version: The version of the template you want to deploy.
      • Answers: Key-value pairs of answers used to deploy the app.
      • Name: The name of the app you want to deploy.
      • TargetNamespace: The target namespace where you want to deploy the app.
      # example
      stages:
      - name: Deploy App
        steps:
        - applyAppConfig:
            catalogTemplate: cattle-global-data:library-mysql
            version: 0.3.8
            answers:
              persistence.enabled: "false"
            name: testmysql
            targetNamespace: test

      Timeouts​

      By default, each pipeline execution has a timeout of 60 minutes. If the pipeline execution cannot complete within its timeout period, the pipeline is aborted.

      Configuring Timeouts by UI​

      Enter a new value in the Timeout field.

      Configuring Timeouts by YAML​

      In the timeout section, enter the timeout value in minutes.

      # example
      stages:
        - name: Build something
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: ls
      # timeout in minutes
      timeout: 30

      Notifications​

      You can enable notifications to any notifiers based on the build status of a pipeline. Before enabling notifications, Rancher recommends setting up notifiers so it will be easy to add recipients immediately.

      Configuring Notifications by UI​

      Available as of v2.2.0

      1. Within the Notification section, turn on notifications by clicking Enable.

      2. Select the conditions for the notification. You can select to get a notification for the following statuses: Failed, Success, Changed. For example, if you want to receive notifications when an execution fails, select Failed.

      3. If you don't have any existing notifiers, Rancher will provide a warning that no notifiers are set up and provide a link to be able to go to the notifiers page. Follow the instructions to add a notifier. If you already have notifiers, you can add them to the notification by clicking the Add Recipient button.

        Note: Notifiers are configured at a cluster level and require a different level of permissions.

      4. For each recipient, select which notifier type from the dropdown. Based on the type of notifier, you can use the default recipient or override the recipient with a different one. For example, if you have a notifier for Slack, you can update which channel to send the notification to. You can add additional notifiers by clicking Add Recipient.

      Configuring Notifications by YAML​

      Available as of v2.2.0

      In the notification section, you will provide the following information:

      • Recipients: This will be the list of notifiers/recipients that will receive the notification.
        • Notifier: The ID of the notifier. This can be found by finding the notifier and selecting View in API to get the ID.
        • Recipient: Depending on the type of the notifier, the "default recipient" can be used or you can override this with a different recipient. For example, when configuring a slack notifier, you select a channel as your default recipient, but if you wanted to send notifications to a different channel, you can select a different recipient.
      • Condition: Select which conditions of when you want the notification to be sent.
      • Message (Optional): If you want to change the default notification message, you can edit this in the yaml. Note: This option is not available in the UI.
      # Example
      stages:
        - name: Build something
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: ls
      notification:
        recipients:
        - # Recipient
          recipient: "#mychannel"
          # ID of Notifier
          notifier: "c-wdcsr:n-c9pg7"
        - recipient: "test@example.com"
          notifier: "c-wdcsr:n-lkrhd"
        # Select which statuses you want the notification to be sent
        condition: ["Failed", "Success", "Changed"]
        # Ability to override the default message (Optional)
        message: "my-message"

      Triggers and Trigger Rules​

      After you configure a pipeline, you can trigger it using different methods:

      • Manually:

        After you configure a pipeline, you can trigger a build using the latest CI definition from Rancher UI. When a pipeline execution is triggered, Rancher dynamically provisions a Kubernetes pod to run your CI tasks and then remove it upon completion.

      • Automatically:

        When you enable a repository for a pipeline, webhooks are automatically added to the version control system. When project users interact with the repo by pushing code, opening pull requests, or creating a tag, the version control system sends a webhook to Rancher Server, triggering a pipeline execution.

        To use this automation, webhook management permission is required for the repository. Therefore, when users authenticate and fetch their repositories, only those on which they have webhook management permission will be shown.

      Trigger rules can be created to have fine-grained control of pipeline executions in your pipeline configuration. Trigger rules come in two types:

      • Run this when: This type of rule starts the pipeline, stage, or step when a trigger explicitly occurs.

      • Do Not Run this when: This type of rule skips the pipeline, stage, or step when a trigger explicitly occurs.

      If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a pipeline is skipped, none of the pipeline is executed. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run.

      Wildcard character (*) expansion is supported in branch conditions.

      Configuring Pipeline Triggers​

      1. From the Global view, navigate to the project that you want to configure a pipeline trigger rule.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

      4. Click on Show Advanced Options.

      5. In the Trigger Rules section, configure rules to run or skip the pipeline.

        1. Click Add Rule. In the Value field, enter the name of the branch that triggers the pipeline.

        2. Optional: Add more branches that trigger a build.

      6. Click Done.

      Configuring Stage Triggers​

      1. From the Global view, navigate to the project that you want to configure a stage trigger rule.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

      4. Find the stage that you want to manage trigger rules, click the Edit icon for that stage.

      5. Click Show advanced options.

      6. In the Trigger Rules section, configure rules to run or skip the stage.

        1. Click Add Rule.

        2. Choose the Type that triggers the stage and enter a value.

          TypeValue
          BranchThe name of the branch that triggers the stage.
          EventThe type of event that triggers the stage. Values are: Push, Pull Request, Tag

      7. Click Save.

      Configuring Step Triggers​

      1. From the Global view, navigate to the project that you want to configure a stage trigger rule.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

      4. Find the step that you want to manage trigger rules, click the Edit icon for that step.

      5. Click Show advanced options.

      6. In the Trigger Rules section, configure rules to run or skip the step.

        1. Click Add Rule.

        2. Choose the Type that triggers the step and enter a value.

          TypeValue
          BranchThe name of the branch that triggers the step.
          EventThe type of event that triggers the step. Values are: Push, Pull Request, Tag

      7. Click Save.

      Configuring Triggers by YAML​

      # example
      stages:
        - name: Build something
          # Conditions for stages
          when:
            branch: master
            event: [ push, pull_request ]
          # Multiple steps run concurrently
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: date -R
            # Conditions for steps
            when:
              branch: [ master, dev ]
              event: push
      # branch conditions for the pipeline
      branch:
        include: [ master, feature/*]
        exclude: [ dev ]

      Environment Variables​

      When configuring a pipeline, certain step types allow you to use environment variables to configure the step's script.

      Configuring Environment Variables by UI​

      1. From the Global view, navigate to the project that you want to configure pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.

      4. Within one of the stages, find the step that you want to add an environment variable for, click the Edit icon.

      5. Click Show advanced options.

      6. Click Add Variable, and then enter a key and value in the fields that appear. Add more variables if needed.

      7. Add your environment variable(s) into either the script or file.

      8. Click Save.

      Configuring Environment Variables by YAML​

      # example
      stages:
        - name: Build something
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY}
            env:
              FIRST_KEY: VALUE
              SECOND_KEY: VALUE2

      Secrets​

      If you need to use security-sensitive information in your pipeline scripts (like a password), you can pass them in using Kubernetes secrets.

      Prerequisite​

      Create a secret in the same project as your pipeline, or explicitly in the namespace where pipeline build pods run.


      Note: Secret injection is disabled on pull request events.

      Configuring Secrets by UI​

      1. From the Global view, navigate to the project that you want to configure pipelines.

      2. Click Resources > Pipelines. In versions before v2.3.0, click Workloads > Pipelines.

      3. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.

      4. Within one of the stages, find the step that you want to use a secret for, click the Edit icon.

      5. Click Show advanced options.

      6. Click Add From Secret. Select the secret file that you want to use. Then choose a key. Optionally, you can enter an alias for the key.

      7. Click Save.

      Configuring Secrets by YAML​

      # example
      stages:
        - name: Build something
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: echo ${ALIAS_ENV}
            # environment variables from project secrets
            envFrom:
            - sourceName: my-secret
              sourceKey: secret-key
              targetKey: ALIAS_ENV

      Pipeline Variable Substitution Reference​

      For your convenience, the following variables are available for your pipeline configuration scripts. During pipeline executions, these variables are replaced by metadata. You can reference them in the form of ${VAR_NAME}.

      Variable NameDescription
      CICD_GIT_REPO_NAMERepository name (Github organization omitted).
      CICD_GIT_URLURL of the Git repository.
      CICD_GIT_COMMITGit commit ID being executed.
      CICD_GIT_BRANCHGit branch of this event.
      CICD_GIT_REFGit reference specification of this event.
      CICD_GIT_TAGGit tag name, set on tag event.
      CICD_EVENTEvent that triggered the build (push, pull_request or tag).
      CICD_PIPELINE_IDRancher ID for the pipeline.
      CICD_EXECUTION_SEQUENCEBuild number of the pipeline.
      CICD_EXECUTION_IDCombination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}.
      CICD_REGISTRYAddress for the Docker registry for the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step.
      CICD_IMAGEName of the image built from the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step. It does not contain the image tag.

      Example

      Global Pipeline Execution Settings​

      After configuring a version control provider, there are several options that can be configured globally on how pipelines are executed in Rancher. These settings can be edited by selecting Tools > Pipelines in the navigation bar. In versions before v2.2.0, you can select Resources > Pipelines.

      Executor Quota​

      Select the maximum number of pipeline executors. The executor quota decides how many builds can run simultaneously in the project. If the number of triggered builds exceeds the quota, subsequent builds will queue until a vacancy opens. By default, the quota is 2. A value of 0 or less removes the quota limit.

      Resource Quota for Executors​

      Available as of v2.2.0

      Configure compute resources for Jenkins agent containers. When a pipeline execution is triggered, a build pod is dynamically provisioned to run your CI tasks. Under the hood, A build pod consists of one Jenkins agent container and one container for each pipeline step. You can manage compute resources for every containers in the pod.

      Edit the Memory Reservation, Memory Limit, CPU Reservation or CPU Limit, then click Update Limit and Reservation.

      To configure compute resources for pipeline-step containers:

      You can configure compute resources for pipeline-step containers in the .rancher-pipeline.yml file.

      In a step, you will provide the following information:

      • CPU Reservation (CpuRequest): CPU request for the container of a pipeline step.
      • CPU Limit (CpuLimit): CPU limit for the container of a pipeline step.
      • Memory Reservation (MemoryRequest): Memory request for the container of a pipeline step.
      • Memory Limit (MemoryLimit): Memory limit for the container of a pipeline step.
      # example
      stages:
        - name: Build something
          steps:
          - runScriptConfig:
              image: busybox
              shellScript: ls
            cpuRequest: 100m
            cpuLimit: 1
            memoryRequest:100Mi
            memoryLimit: 1Gi
          - publishImageConfig:
              dockerfilePath: ./Dockerfile
              buildContext: .
              tag: repo/app:v1
            cpuRequest: 100m
            cpuLimit: 1
            memoryRequest:100Mi
            memoryLimit: 1Gi

      Note: Rancher sets default compute resources for pipeline steps except for Build and Publish Images and Run Script steps. You can override the default value by specifying compute resources in the same way.

      Custom CA​

      Available as of v2.2.0

      If you want to use a version control provider with a certificate from a custom/internal CA root, the CA root certificates need to be added as part of the version control provider configuration in order for the pipeline build pods to succeed.

      1. Click Edit cacerts.

      2. Paste in the CA root certificates and click Save cacerts.

      Result: Pipelines can be used and new pods will be able to work with the self-signed-certificate.

      Persistent Data for Pipeline Components​

      The internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

      For details on setting up persistent storage for pipelines, refer to this page.

      Example rancher-pipeline.yml​

      An example pipeline configuration file is on this page.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/pipelines/v2.0.x.html b/v2.0-v2.4/reference-guides/pipelines/v2.0.x.html index 6af28903fb0..aa5ae0c176f 100644 --- a/v2.0-v2.4/reference-guides/pipelines/v2.0.x.html +++ b/v2.0-v2.4/reference-guides/pipelines/v2.0.x.html @@ -5,14 +5,14 @@ v2.0.x Pipeline Documentation | Rancher Manager - +
      Version: v2.0-v2.4

      v2.0.x Pipeline Documentation

      Note: This section describes the pipeline feature as implemented in Rancher v2.0.x. If you are using Rancher v2.1 or later, where pipelines have been significantly improved, please refer to the new documentation for v2.1 or later.

      Pipelines help you automate the software delivery process. You can integrate Rancher with GitHub to create a pipeline.

      You can set up your pipeline to run a series of stages and steps to test your code and deploy it.

      Pipelines
      Contain a series of stages and steps. Out-of-the-box, the pipelines feature supports fan out and in capabilities.
      Stages
      Executed sequentially. The next stage will not execute until all of the steps within the stage execute.
      Steps
      Are executed in parallel within a stage.

      Enabling CI Pipelines​

      1. Select cluster from drop down.

      2. Under tools menu select pipelines.

      3. Follow instructions for setting up github auth on page.

      Creating CI Pipelines​

      1. Go to the project you want this pipeline to run in.

      2. Click Resources > Pipelines. In versions before v2.3.0,click Workloads > Pipelines.

      3. Click Add pipeline button.

      4. Enter in your repository name (Autocomplete should help zero in on it quickly).

      5. Select Branch options.

        • Only the branch {BRANCH NAME}: Only events triggered by changes to this branch will be built.

        • Everything but {BRANCH NAME}: Build any branch that triggered an event EXCEPT events from this branch.

        • All branches: Regardless of the branch that triggered the event always build.

        Note: If you want one path for master, but another for PRs or development/test/feature branches, create two separate pipelines.

      6. Select the build trigger events. By default, builds will only happen by manually clicking build now in Rancher UI.

        • Automatically build this pipeline whenever there is a git commit. (This respects the branch selection above)

        • Automatically build this pipeline whenever there is a new PR.

        • Automatically build the pipeline. (Allows you to configure scheduled builds similar to Cron)

      7. Click Add button.

        By default, Rancher provides a three stage pipeline for you. It consists of a build stage where you would compile, unit test, and scan code. The publish stage has a single step to publish a docker image.

      1. Add a name to the pipeline in order to complete adding a pipeline.

      2. Click on the ‘run a script’ box under the ‘Build’ stage.

        Here you can set the image, or select from pre-packaged envs.

      3. Configure a shell script to run inside the container when building.

      4. Click Save to persist the changes.

      5. Click the “publish an image’ box under the “Publish” stage.

      6. Set the location of the Dockerfile. By default it looks in the root of the workspace. Instead, set the build context for building the image relative to the root of the workspace.

      7. Set the image information.

        The registry is the remote registry URL. It is defaulted to Docker hub. Repository is the <org>/<repo> in the repository.

      8. Select the Tag. You can hard code a tag like ‘latest’ or select from a list of available variables.

      9. If this is the first time using this registry, you can add the username/password for pushing the image. You must click save for the registry credentials AND also save for the modal.

      Creating a New Stage​

      1. To add a new stage the user must click the ‘add a new stage’ link in either create or edit mode of the pipeline view.

      2. Provide a name for the stage.

      3. Click save.

      Creating a New Step​

      1. Go to create / edit mode of the pipeline.

      2. Click “Add Step” button in the stage that you would like to add a step in.

      3. Fill out the form as detailed above

      Environment Variables​

      For your convenience the following environment variables are available in your build steps:

      Variable NameDescription
      CICD_GIT_REPO_NAMERepository Name (Stripped of Github Organization)
      CICD_PIPELINE_NAMEName of the pipeline
      CICD_GIT_BRANCHGit branch of this event
      CICD_TRIGGER_TYPEEvent that triggered the build
      CICD_PIPELINE_IDRancher ID for the pipeline
      CICD_GIT_URLURL of the Git repository
      CICD_EXECUTION_SEQUENCEBuild number of the pipeline
      CICD_EXECUTION_IDCombination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}
      CICD_GIT_COMMITGit commit ID being executed.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-cluster-tools.html b/v2.0-v2.4/reference-guides/rancher-cluster-tools.html index d3d62e39f71..23d0930597e 100644 --- a/v2.0-v2.4/reference-guides/rancher-cluster-tools.html +++ b/v2.0-v2.4/reference-guides/rancher-cluster-tools.html @@ -5,13 +5,13 @@ Tools for Logging, Monitoring, and More | Rancher Manager - +
      Version: v2.0-v2.4

      Tools for Logging, Monitoring, and More

      Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

      Logging

      Logging is helpful because it allows you to:

      • Capture and analyze the state of your cluster
      • Look for trends in your environment
      • Save your logs to a safe location outside of your cluster
      • Stay informed of events like a container crashing, a pod eviction, or a node dying
      • More easily debugg and troubleshoot problems

      Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

      Refer to the logging documentation here.

      Monitoring

      Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.

      For details, refer to Monitoring.

      Alerts

      After monitoring is enabled, you can set up alerts and notifiers that provide the mechanism to receive them.

      Alerts are rules that trigger notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

      For details, refer to Alerts.

      Notifiers

      Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

      For details, refer to Notifiers.

      Istio

      Available as of v2.3

      Istio is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.

      Refer to the Istio documentation here.

      OPA Gatekeeper

      OPA Gatekeeper is an open-source project that provides integration between OPA and Kubernetes to provide policy control via admission controller webhooks. For details on how to enable Gatekeeper in Rancher, refer to the OPA Gatekeeper section.

      CIS Scans

      Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.

      Refer to the CIS scan documentation here.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.html b/v2.0-v2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.html index fc8ffcdb057..df7dcc6a738 100644 --- a/v2.0-v2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.html +++ b/v2.0-v2.4/reference-guides/rancher-manager-architecture/architecture-recommendations.html @@ -5,13 +5,13 @@ Architecture Recommendations | Rancher Manager - +
      Version: v2.0-v2.4

      Architecture Recommendations

      Kubernetes cluster. If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the cluster running Rancher should be separate from downstream clusters.

      Separation of Rancher and User Clusters

      A user cluster is a downstream Kubernetes cluster that runs your apps and services.

      If you have a Docker installation of Rancher, the node running the Rancher server should be separate from your downstream clusters.

      In Kubernetes installations of Rancher, the Rancher server cluster should also be separate from the user clusters.

      Separation of Rancher Server from User Clusters

      Why HA is Better for Rancher in Production

      We recommend installing the Rancher server on a high-availability Kubernetes cluster, primarily because it protects the Rancher server data. In a high-availability installation, a load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure.

      We don't recommend installing Rancher in a single Docker container, because if the node goes down, there is no copy of the cluster data available on other nodes and you could lose the data on your Rancher server.

      As of v2.4, Rancher needs to be installed on either a high-availability RKE (Rancher Kubernetes Engine) Kubernetes cluster, or a high-availability K3s (Lightweight Kubernetes) Kubernetes cluster. Both RKE and K3s are fully certified Kubernetes distributions.

      Rancher versions before v2.4 need to be installed on an RKE cluster.

      K3s Kubernetes Cluster Installations​

      If you are installing Rancher v2.4 for the first time, we recommend installing it on a K3s Kubernetes cluster. One main advantage of this K3s architecture is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.

      The option to install Rancher on a K3s cluster is a feature introduced in Rancher v2.4. K3s is easy to install, with half the memory of Kubernetes, all in a binary less than 100 MB.

      Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

      Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

      RKE Kubernetes Cluster Installations​

      If you are installing Rancher before v2.4, you will need to install Rancher on an RKE cluster, in which the cluster data is stored on each node with the etcd role. As of Rancher v2.4, there is no migration path to transition the Rancher server from an RKE cluster to a K3s cluster. All versions of the Rancher server, including v2.4+, can be installed on an RKE cluster.

      In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.

      Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server

      Architecture of an RKE Kubernetes cluster running the Rancher management server

      Recommended Load Balancer Configuration for Kubernetes Installations

      We recommend the following configurations for the load balancer and Ingress controllers:

      • The DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
      • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
      • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
      • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
      Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at Ingress controllers

      Rancher HA

      Environment for Kubernetes Installations

      It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine.

      For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

      It is not recommended to install Rancher on top of a managed Kubernetes service such as Amazon’s EKS or Google Kubernetes Engine. These hosted Kubernetes solutions do not expose etcd to a degree that is manageable for Rancher, and their customizations can interfere with Rancher operations.

      Recommended Node Roles for Kubernetes Installations

      Our recommendations for the roles of each node differ depending on whether Rancher is installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.

      K3s Cluster Roles​

      In K3s clusters, there are two types of nodes: server nodes and agent nodes. Both servers and agents can have workloads scheduled on them. Server nodes run the Kubernetes master.

      For the cluster running the Rancher management server, we recommend using two server nodes. Agent nodes are not required.

      RKE Cluster Roles​

      If Rancher is installed on an RKE Kubernetes cluster, the cluster should have three nodes, and each node should have all three Kubernetes roles: etcd, controlplane, and worker.

      Contrasting RKE Cluster Architecture for Rancher Server and for Downstream Kubernetes Clusters​

      Our recommendation for RKE node roles on the Rancher server cluster contrasts with our recommendations for the downstream user clusters that run your apps and services.

      Rancher uses RKE as a library when provisioning downstream Kubernetes clusters. Note: The capability to provision downstream K3s clusters will be added in a future version of Rancher.

      For downstream Kubernetes clusters, we recommend that each node in a user cluster should have a single role for stability and scalability.

      Kubernetes Roles for Nodes in Rancher Server Cluster vs. User Clusters

      RKE only requires at least one node with each role and does not require nodes to be restricted to one role. However, for the clusters that run your apps, we recommend separate roles for each node so that workloads on worker nodes don't interfere with the Kubernetes master or cluster data as your services scale.

      We recommend that downstream user clusters should have at least:

      • Three nodes with only the etcd role to maintain a quorum if one node is lost, making the state of your cluster highly available
      • Two nodes with only the controlplane role to make the master component highly available
      • One or more nodes with only the worker role to run the Kubernetes node components, as well as the workloads for your apps and services

      With that said, it is safe to use all three roles on three nodes when setting up the Rancher server because:

      • It allows one etcd node failure.
      • It maintains multiple instances of the master components by having multiple controlplane nodes.
      • No other workloads than Rancher itself should be created on this cluster.

      Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of downstream clusters.

      For more best practices for downstream clusters, refer to the production checklist or our best practices guide.

      Architecture for an Authorized Cluster Endpoint

      If you are using an authorized cluster endpoint, we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the controlplane role.

      If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate, which will be included in the generated kubeconfig file to validate the certificate chain. See the documentation on kubeconfig files and API keys for more information.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html b/v2.0-v2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html index 092e9f52fe3..ba84b5452ea 100644 --- a/v2.0-v2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html +++ b/v2.0-v2.4/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html @@ -5,14 +5,14 @@ Communicating with Downstream User Clusters | Rancher Manager - +
      Version: v2.0-v2.4

      Communicating with Downstream User Clusters

      This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services.

      The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters.

      Communicating with Downstream Clusters

      Rancher Components

      The following descriptions correspond to the numbers in the diagram above:

      1. The Authentication Proxy
      2. Cluster Controllers and Cluster Agents
      3. Node Agents
      4. Authorized Cluster Endpoint

      1. The Authentication Proxy​

      In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a kubectl command to see the pods. Bob is authenticated through Rancher's authentication proxy.

      The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.

      Rancher communicates with Kubernetes clusters using a service account, which provides an identity for processes that run in a pod.

      By default, Rancher generates a kubeconfig file that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (kube_config_rancher-cluster.yml) contains full access to the cluster.

      2. Cluster Controllers and Cluster Agents​

      Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server.

      There is one cluster controller and one cluster agent for each downstream cluster. Each cluster controller:

      • Watches for resource changes in the downstream cluster
      • Brings the current state of the downstream cluster to the desired state
      • Configures access control policies to clusters and projects
      • Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE

      By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a node agent instead.

      The cluster agent, also called cattle-cluster-agent, is a component that runs in a downstream user cluster. It performs the following tasks:

      • Connects to the Kubernetes API of Rancher-launched Kubernetes clusters
      • Manages workloads, pod creation and deployment within each cluster
      • Applies the roles and bindings defined in each cluster's global policies
      • Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health

      3. Node Agents​

      If the cluster agent (also called cattle-cluster-agent) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.

      The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.

      4. Authorized Cluster Endpoint​

      An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy.

      The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher used RKE to provision the cluster. It is not available for imported clusters, or for clusters in a hosted Kubernetes provider, such as Amazon's EKS.

      There are two main reasons why a user might need the authorized cluster endpoint:

      • To access a downstream user cluster while Rancher is down
      • To reduce latency in situations where the Rancher server and downstream cluster are separated by a long distance

      The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

      Like the authorized cluster endpoint, the kube-api-auth authentication service is also only available for Rancher-launched Kubernetes clusters.

      Example scenario: Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint.

      With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for kubectl and helm.

      You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the section on accessing your cluster with kubectl and the kubeconfig file.

      Important Files​

      The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:

      • rancher-cluster.yml: The RKE cluster configuration file.
      • kube_config_rancher-cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down.
      • rancher-cluster.rkestate: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher.

      Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

      For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the kubeconfig file documentation.

      Tools for Provisioning Kubernetes Clusters​

      The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.

      Rancher Launched Kubernetes for Nodes Hosted in an Infrastructure Provider​

      Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

      Rancher provisions this type of cluster using RKE and docker-machine.

      Rancher Launched Kubernetes for Custom Nodes​

      When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster.

      Rancher provisions this type of cluster using RKE.

      Hosted Kubernetes Providers​

      When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

      Rancher provisions this type of cluster using kontainer-engine.

      Imported Kubernetes Clusters​

      In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

      Rancher Server Components and Source Code​

      This diagram shows each component that the Rancher server is composed of:

      Rancher Components

      The GitHub repositories for Rancher can be found at the following links:

      This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on contributing to Rancher. To see all libraries and projects used in Rancher, see the go.mod file in the rancher/rancher repository.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.html b/v2.0-v2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.html index d2a1a7cc556..e109484c822 100644 --- a/v2.0-v2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.html +++ b/v2.0-v2.4/reference-guides/rancher-manager-architecture/rancher-server-and-components.html @@ -5,13 +5,13 @@ Rancher Server and Components | Rancher Manager - +
      Version: v2.0-v2.4

      Rancher Server and Components

      The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment.

      The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service).

      For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

      The diagram below shows how users can manipulate both Rancher-launched Kubernetes clusters and hosted Kubernetes clusters through Rancher's authentication proxy:

      Managing Kubernetes Clusters through Rancher's Authentication Proxy

      Architecture

      You can install Rancher on a single node, or on a high-availability Kubernetes cluster.

      A high-availability Kubernetes installation is recommended for production.

      A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:

      For Rancher v2.0-v2.4, there was no migration path from a Docker installation to a high-availability installation. Therefore, you may want to use a Kubernetes installation from the start.

      The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages.

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-project-tools/project-alerts.html b/v2.0-v2.4/reference-guides/rancher-project-tools/project-alerts.html index 905fbc9d0cb..71aec89f491 100644 --- a/v2.0-v2.4/reference-guides/rancher-project-tools/project-alerts.html +++ b/v2.0-v2.4/reference-guides/rancher-project-tools/project-alerts.html @@ -5,13 +5,13 @@ Project Alerts | Rancher Manager - +
      Version: v2.0-v2.4

      Project Alerts

      To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned. When an event occurs, your alert is triggered, and you are sent a notification. You can then, if necessary, follow up with corrective actions.

      Notifiers and alerts are built on top of the Prometheus Alertmanager. Leveraging these tools, Rancher can notify cluster owners and project owners of events they need to address.

      Before you can receive alerts, one or more notifier must be configured at the cluster level.

      Only administrators, cluster owners or members, or project owners can manage project alerts.

      Alerts Scope​

      The scope for alerts can be set at either the cluster level or project level.

      At the project level, Rancher monitors specific deployments and sends alerts for:

      • Deployment availability
      • Workloads status
      • Pod status
      • The Prometheus expression cross the thresholds

      Default Project-level Alerts​

      When you enable monitoring for the project, some project-level alerts are provided. You can receive these alerts if a notifier for them is configured at the cluster level.

      AlertExplanation
      Less than half workload availableA critical alert is triggered if less than half of a workload is available, based on workloads where the key is app and the value is workload.
      Memory usage close to the quotaA warning alert is triggered if the workload's memory usage exceeds the memory resource quota that is set for the workload. You can see the memory limit in the Rancher UI if you go to the workload under the Security & Host Config tab.

      For information on other default alerts, refer to the section on cluster-level alerts.

      Adding Project Alerts​

      Prerequisite: Before you can receive project alerts, you must add a notifier.

      1. From the Global view, navigate to the project that you want to configure project alerts for. Select Tools > Alerts. In versions before v2.2.0, you can choose Resources > Alerts.

      2. Click Add Alert Group.

      3. Enter a Name for the alert that describes its purpose, you could group alert rules for the different purpose.

      4. Based on the type of alert you want to create, fill out the form. For help, refer to the configuration section below.

      5. Continue adding more alert rules to the group.

      6. Finally, choose the notifiers that send you alerts.

        • You can set up multiple notifiers.
        • You can change notifier recipients on the fly.

      7. Click Create.

      Result: Your alert is configured. A notification is sent when the alert is triggered.

      Managing Project Alerts​

      To manage project alerts, browse to the project that alerts you want to manage. Then select Tools > Alerts. In versions before v2.2.0, you can choose Resources > Alerts. You can:

      • Deactivate/Reactive alerts
      • Edit alert settings
      • Delete unnecessary alerts
      • Mute firing alerts
      • Unmute muted alerts

      Project Alert Rule Configuration​

      Pod Alerts​

      This alert type monitors for the status of a specific pod.

      Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

      When a​

      Select the Pod option, and then select a pod from the drop-down.

      Is​

      Select a pod status that triggers an alert:

      • Not Running
      • Not Scheduled
      • Restarted <x> times within the last <x> Minutes

      Send a​

      Select the urgency level of the alert. The options are:

      • Critical: Most urgent
      • Warning: Normal urgency
      • Info: Least urgent

      Select the urgency level of the alert based on pod state. For example, select Info for Job pod which stop running after job finished. However, if an important pod isn't scheduled, it may affect operations, so choose Critical.

      Advanced Options​

      By default, the below options will apply to all alert rules within the group.

      You can disable these advanced options when configuring a specific rule.

      • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
      • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
      • Repeat Wait Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour.

      Workload Alerts​

      This alert type monitors for the availability of a workload.

      Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

      When a​

      Choose the Workload option. Then choose a workload from the drop-down.

      Is​

      Choose an availability percentage using the slider. The alert is triggered when the workload's availability on your cluster nodes drops below the set percentage.

      Send a​

      Select the urgency level of the alert.

      • Critical: Most urgent
      • Warning: Normal urgency
      • Info: Least urgent

      Select the urgency level of the alert based on the percentage you choose and the importance of the workload.

      Advanced Options​

      By default, the below options will apply to all alert rules within the group.

      You can disable these advanced options when configuring a specific rule.

      • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
      • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
      • Repeat Wait Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour.

      Workload Selector Alerts​

      This alert type monitors for the availability of all workloads marked with tags that you've specified.

      Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

      When a​

      Select the Workload Selector option, and then click Add Selector to enter the key value pair for a label. If one of the workloads drops below your specifications, an alert is triggered. This label should be applied to one or more of your workloads.

      Is​

      Choose an availability percentage using the slider. The alert is triggered when the workload's availability on your cluster nodes drops below the set percentage.

      Send a​

      Select the urgency level of the alert.

      • Critical: Most urgent
      • Warning: Normal urgency
      • Info: Least urgent

      Select the urgency level of the alert based on the percentage you choose and the importance of the workload.

      Advanced Options​

      By default, the below options will apply to all alert rules within the group.

      You can disable these advanced options when configuring a specific rule.

      • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
      • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
      • Repeat Wait Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour.

      Metric Expression Alerts​

      Available as of v2.2.4

      If you enable project monitoring, this alert type monitors for the overload from Prometheus expression querying.

      Each of the below sections corresponds to a part of the alert rule configuration section in the Rancher UI.

      When A​

      Input or select an Expression. The dropdown shows the original metrics from Prometheus, including:

      Is​

      Choose a comparison.

      • Equal: Trigger alert when expression value equal to the threshold.
      • Not Equal: Trigger alert when expression value not equal to the threshold.
      • Greater Than: Trigger alert when expression value greater than to threshold.
      • Less Than: Trigger alert when expression value equal or less than the threshold.
      • Greater or Equal: Trigger alert when expression value greater to equal to the threshold.
      • Less or Equal: Trigger alert when expression value less or equal to the threshold.

      If applicable, choose a comparison value or a threshold for the alert to be triggered.

      For​

      Select a duration for a trigger alert when the expression value crosses the threshold longer than the configured duration.

      Send a​

      Select the urgency level of the alert.

      • Critical: Most urgent
      • Warning: Normal urgency
      • Info: Least urgent

      Select the urgency level of the alert based on its impact on operations. For example, an alert triggered when a expression for container memory close to the limit raises above 60% deems an urgency of Info, but raised about 95% deems an urgency of Critical.

      Advanced Options​

      By default, the below options will apply to all alert rules within the group. You can disable these advanced options when configuring a specific rule.

      • Group Wait Time: How long to wait to buffer alerts of the same group before sending initially, default to 30 seconds.
      • Group Interval Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 30 seconds.
      • Repeat Wait Time: How long to wait before sending an alert that has been added to a group which contains already fired alerts, default to 1 hour.
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-project-tools/project-logging.html b/v2.0-v2.4/reference-guides/rancher-project-tools/project-logging.html index 0a5ae166505..3442d4cae36 100644 --- a/v2.0-v2.4/reference-guides/rancher-project-tools/project-logging.html +++ b/v2.0-v2.4/reference-guides/rancher-project-tools/project-logging.html @@ -5,13 +5,13 @@ Project Logging | Rancher Manager - +
      Version: v2.0-v2.4

      Project Logging

      Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters.

      For background information about how logging integrations work, refer to the cluster administration section.

      Rancher supports the following services:

      • Elasticsearch
      • Splunk
      • Kafka
      • Syslog
      • Fluentd

      Note: You can only configure one logging service per cluster or per project.

      Only administrators, cluster owners or members, or project owners can configure Rancher to send Kubernetes logs to a logging service.

      Requirements

      The Docker daemon on each node in the cluster should be configured with the (default) log-driver: json-file. You can check the log-driver by running the following command:

      $ docker info | grep 'Logging Driver'
      Logging Driver: json-file

      Advantages

      Setting up a logging service to collect logs from your cluster/project has several advantages:

      • Logs errors and warnings in your Kubernetes infrastructure to a stream. The stream informs you of events like a container crashing, a pod eviction, or a node dying.
      • Allows you to capture and analyze the state of your cluster and look for trends in your environment using the log stream.
      • Helps you when troubleshooting or debugging.
      • Saves your logs to a safe location outside of your cluster, so that you can still access them even if your cluster encounters issues.

      Logging Scope

      You can configure logging at either cluster level or project level.

      • Cluster logging writes logs for every pod in the cluster, i.e. in all the projects. For RKE clusters, it also writes logs for all the Kubernetes system components.

      • Project logging writes logs for every pod in that particular project.

      Logs that are sent to your logging service are from the following locations:

      • Pod logs stored at /var/log/containers.

      • Kubernetes system components logs stored at /var/lib/rancher/rke/logs/.

      Enabling Project Logging

      1. From the Global view, navigate to the project that you want to configure project logging.

      2. Select Tools > Logging in the navigation bar. In versions before v2.2.0, you can choose Resources > Logging.

      3. Select a logging service and enter the configuration. Refer to the specific service for detailed configuration. Rancher supports the following services:

      4. (Optional) Instead of using the UI to configure the logging services, you can enter custom advanced configurations by clicking on Edit as File, which is located above the logging targets. This link is only visible after you select a logging service.

        • With the file editor, enter raw fluentd configuration for any logging service. Refer to the documentation for each logging service on how to setup the output configuration.

        • If the logging service is using TLS, you also need to complete the SSL Configuration form.

          1. Provide the Client Private Key and Client Certificate. You can either copy and paste them or upload them by using the Read from a file button.

            • You can use either a self-signed certificate or one provided by a certificate authority.

            • You can generate a self-signed certificate using an openssl command. For example:

              openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

          2. If you are using a self-signed certificate, provide the CA Certificate PEM.

      5. (Optional) Complete the Additional Logging Configuration form.

        1. Optional: Use the Add Field button to add custom log fields to your logging configuration. These fields are key value pairs (such as foo=bar) that you can use to filter the logs from another system.

        2. Enter a Flush Interval. This value determines how often Fluentd flushes data to the logging server. Intervals are measured in seconds.

        3. Include System Log. The logs from pods in system project and RKE components will be sent to the target. Uncheck it to exclude the system logs.

      6. Click Test. Rancher sends a test log to the service.

        Note: This button is replaced with Dry Run if you are using the custom configuration editor. In this case, Rancher calls the fluentd dry run command to validate the configuration.

      7. Click Save.

      Result: Rancher is now configured to send logs to the selected service. Log into the logging service so that you can start viewing the logs.

      Related Links

      Logging Architecture

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/hardening-guide-with-cis-v1.3-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/hardening-guide-with-cis-v1.3-benchmark.html index 4decea29f25..0c9d15dd4f7 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/hardening-guide-with-cis-v1.3-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/hardening-guide-with-cis-v1.3-benchmark.html @@ -5,14 +5,14 @@ Hardening Guide v2.1 | Rancher Manager - +
      Version: v2.0-v2.4

      Hardening Guide v2.1

      This document provides prescriptive guidance for hardening a production installation of Rancher v2.1.x. It outlines the configurations and controls required to address Kubernetes benchmark controls from the Center for Information Security (CIS).

      This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes.

      This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.1Rancher v2.1.xBenchmark v1.3.0Kubernetes 1.11

      Click here to download a PDF version of this document

      For more detail on how a hardened cluster scores against the official CIS benchmark, refer to the CIS Benchmark Rancher Self-Assessment Guide - Rancher v2.1.x.

      Profile Definitions​

      The following profile definitions agree with the CIS benchmarks for Kubernetes.

      A profile is a set of configurations that provide a certain amount of hardening. Generally, the more hardened an environment is, the more it affects performance.

      Level 1​

      Items in this profile intend to:

      • offer practical advice appropriate for the environment;
      • deliver an obvious security benefit; and
      • not alter the functionality or utility of the environment beyond an acceptable margin

      Level 2​

      Items in this profile extend the “Level 1” profile and exhibit one or more of the following characteristics:

      • are intended for use in environments or use cases where security is paramount
      • act as a defense in depth measure
      • may negatively impact the utility or performance of the technology

      1.1 - Rancher HA Kubernetes cluster host configuration​

      1.1.1 - Configure default sysctl settings on all hosts​

      Profile Applicability

      • Level 1

      Description

      Configure sysctl settings to match what the kubelet would set if allowed.

      Rationale

      We recommend that users launch the kubelet with the --protect-kernel-defaults option. The settings that the kubelet initially attempts to change can be set manually.

      This supports the following control:

      • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)

      Audit

      • Verify vm.overcommit_memory = 1
      sysctl vm.overcommit_memory
      • Verify kernel.panic = 10
      sysctl kernel.panic
      • Verify kernel.panic_on_oops = 1
      sysctl kernel.panic_on_oops

      Remediation

      • Set the following parameters in /etc/sysctl.conf on all nodes:
      vm.overcommit_memory=1
      kernel.panic=10
      kernel.panic_on_oops=1
      • Run sysctl -p to enable the settings.

      1.1.2 - Install the encryption provider configuration on all control plane nodes​

      Profile Applicability

      • Level 1

      Description

      Create a Kubernetes encryption configuration file on each of the RKE nodes that will be provisioned with the controlplane role:

      Rationale

      This configuration file will ensure that the Rancher RKE cluster encrypts secrets at rest, which Kubernetes does not do by default.

      This supports the following controls:

      • 1.1.34 - Ensure that the --experimental-encryption-provider-config argument is set as appropriate (Scored)
      • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)

      Audit

      On the control plane hosts for the Rancher HA cluster run:

      stat /etc/kubernetes/encryption.yaml

      Ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root
      • The file contains:
      apiVersion: v1
      kind: EncryptionConfig
      resources:
      - resources:
          - secrets
          providers:
          - aescbc:
              keys:
              - name: key1
                secret: <32-byte base64 encoded string>
          - identity: {}

      Where aescbc is the key type, and secret is populated with a 32-byte base64 encoded string.

      Remediation

      • Generate a key and an empty configuration file:
      head -c 32 /dev/urandom | base64 -i -
      touch /etc/kubernetes/encryption.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /etc/kubernetes/encryption.yaml
      chmod 0600 /etc/kubernetes/encryption.yaml
      • Set the contents to:
      apiVersion: v1
      kind: EncryptionConfig
      resources:
        - resources:
          - secrets
          providers:
          - aescbc:
              keys:
              - name: key1
                secret: <32-byte base64 encoded string>
          - identity: {}

      Where secret is the 32-byte base64-encoded string generated in the first step.

      1.1.3 - Install the audit log configuration on all control plane nodes.​

      Profile Applicability

      • Level 1

      Description

      Place the configuration file for Kubernetes audit logging on each of the control plane nodes in the cluster.

      Rationale

      The Kubernetes API has audit logging capability that is the best way to track actions in the cluster.

      This supports the following controls:

      • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
      • 1.1.16 - Ensure that the --audit-log-maxage argument is as appropriate (Scored)
      • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
      • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
      • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

      Audit

      On each control plane node, run:

      stat /etc/kubernetes/audit.yaml

      Ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root
      • The file contains:
      apiVersion: audit.k8s.io/v1beta1
      kind: Policy
      rules:
      - level: Metadata

      Remediation

      On nodes with the controlplane role:

      • Generate an empty configuration file:
      touch /etc/kubernetes/audit.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /etc/kubernetes/audit.yaml
      chmod 0600 /etc/kubernetes/audit.yaml
      • Set the contents to:
      apiVersion: audit.k8s.io/v1beta1
      kind: Policy
      rules:
      - level: Metadata

      1.1.4 - Place Kubernetes event limit configuration on each control plane host​

      Profile Applicability

      • Level 1

      Description

      Place the configuration file for Kubernetes event limit configuration on each of the control plane nodes in the cluster.

      Rationale

      Set up the EventRateLimit admission control plugin to prevent clients from overwhelming the API server. The settings below are intended as an initial value and may need to be adjusted for larger clusters.

      This supports the following control:

      • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)

      Audit

      On nodes with the controlplane role run:

      stat /etc/kubernetes/admission.yaml
      stat /etc/kubernetes/event.yaml

      For each file, ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root

      For admission.yaml ensure that the file contains:

      apiVersion: apiserver.k8s.io/v1alpha1
      kind: AdmissionConfiguration
      plugins:
      - name: EventRateLimit
        path: /etc/kubernetes/event.yaml

      For event.yaml ensure that the file contains:

      apiVersion: eventratelimit.admission.k8s.io/v1alpha1
      kind: Configuration
      limits:
      - type: Server
        qps: 500
        burst: 5000

      Remediation

      On nodes with the controlplane role:

      • Generate an empty configuration file:
      touch /etc/kubernetes/admission.yaml
      touch /etc/kubernetes/event.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /etc/kubernetes/admission.yaml
      chown root:root /etc/kubernetes/event.yaml
      chmod 0600 /etc/kubernetes/admission.yaml
      chmod 0600 /etc/kubernetes/event.yaml
      • For admission.yaml set the contents to:
      apiVersion: apiserver.k8s.io/v1alpha1
      kind: AdmissionConfiguration
      plugins:
      - name: EventRateLimit
        path: /etc/kubernetes/event.yaml
      • For event.yaml set the contents to:
      apiVersion: eventratelimit.admission.k8s.io/v1alpha1
      kind: Configuration
      limits:
      - type: Server
        qps: 500
        burst: 5000

      2.1 - Rancher HA Kubernetes Cluster Configuration via RKE​

      (See Appendix A. for full RKE cluster.yml example)

      2.1.1 - Configure kubelet options​

      Profile Applicability

      • Level 1

      Description

      Ensure Kubelet options are configured to match CIS controls.

      Rationale

      To pass the following controls in the CIS benchmark, ensure the appropriate flags are passed to the Kubelet.

      • 2.1.6 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)
      • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)
      • 2.1.8 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)
      • 2.1.10 - Ensure that the --event-qps argument is set to 0 (Scored)

      Audit

      Inspect the Kubelet containers on all hosts and verify that they are running with the following options:

      • --streaming-connection-idle-timeout=<duration greater than 0>
      • --protect-kernel-defaults=true
      • --make-iptables-util-chains=true
      • --event-qps=0

      Remediation

      • Add the following to the RKE cluster.yml kubelet section under services:
      services:
        kubelet:
          extra_args:
            streaming-connection-idle-timeout: "<duration>"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"

      Where <duration> is in a form like 1800s.

      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.2 - Configure kube-api options​

      Profile Applicability

      • Level 1

      Description

      Ensure the RKE configuration is set to deploy the kube-api service with the options required for controls.

      Rationale

      To pass the following controls for the kube-api server ensure RKE configuration passes the appropriate options.

      • 1.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
      • 1.1.8 - Ensure that the --profiling argument is set to false (Scored)
      • 1.1.9 - Ensure that the --repair-malformed-updates argument is set to false (Scored)
      • 1.1.11 - Ensure that the admission control plugin AlwaysPullImages is set (Scored)
      • 1.1.12 - Ensure that the admission control plugin DenyEscalatingExec is set (Scored)
      • 1.1.14 - Ensure that the admission control plugin NamespaceLifecycle is set (Scored)
      • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
      • 1.1.16 - Ensure that the --audit-log-maxage argument is set as appropriate (Scored)
      • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
      • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
      • 1.1.23 - Ensure that the --service-account-lookup argument is set to true (Scored)
      • 1.1.24 - Ensure that the admission control plugin PodSecurityPolicy is set (Scored)
      • 1.1.34 - Ensure that the --experimental-encryption-provider-config argument is set as appropriate (Scored)
      • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)
      • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)
      • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-apiserver containers:

        docker inspect kube-apiserver

      • Look for the following options in the command section of the output:

      --anonymous-auth=false
      --profiling=false
      --repair-malformed-updates=false
      --service-account-lookup=true
      --enable-admission-plugins= "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
      --experimental-encryption-provider-config=/etc/kubernetes/encryption.yaml
      --admission-control-config-file=/etc/kubernetes/admission.yaml
      --audit-log-path=/var/log/kube-audit/audit-log.json
      --audit-log-maxage=5
      --audit-log-maxbackup=5
      --audit-log-maxsize=100
      --audit-log-format=json
      --audit-policy-file=/etc/kubernetes/audit.yaml
      • In the volume section of the output ensure the bind mount is present:
      /var/log/kube-audit:/var/log/kube-audit

      Remediation

      • In the RKE cluster.yml add the following directives to the kube-api section under services:
      services:
        kube-api:
          pod_security_policy: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            repair-malformed-updates: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            experimental-encryption-provider-config: /etc/kubernetes/encryption.yaml
            admission-control-config-file: "/etc/kubernetes/admission.yaml"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            audit-policy-file: /etc/kubernetes/audit.yaml
          extra_binds:
            - "/var/log/kube-audit:/var/log/kube-audit"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.3 - Configure scheduler options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate options for the Kubernetes scheduling service.

      Rationale

      To address the following controls on the CIS benchmark, the command line options should be set on the Kubernetes scheduler.

      • 1.2.1 - Ensure that the --profiling argument is set to false (Scored)
      • 1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role: inspect the kube-scheduler containers:
      docker inspect kube-scheduler
      • Verify the following options are set in the command section.
      --profiling=false
      --address=127.0.0.1

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        …
        scheduler:
          extra_args:
          profiling: "false"
          address: "127.0.0.1"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.4 - Configure controller options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate arguments on the Kubernetes controller manager.

      Rationale

      To address the following controls the options need to be passed to the Kubernetes controller manager.

      • 1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)
      • 1.3.2 - Ensure that the --profiling argument is set to false (Scored)
      • 1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-controller-manager container:
      docker inspect kube-controller-manager
      • Verify the following options are set in the command section:
      --terminated-pod-gc-threshold=1000
      --profiling=false
      --address=127.0.0.1

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.5 - Configure addons and PSPs​

      Profile Applicability

      • Level 1

      Description

      Configure a restrictive PodSecurityPolicy (PSP) as the default and create role bindings for system level services to use the less restrictive default PSP.

      Rationale

      To address the following controls, a restrictive default PSP needs to be applied as the default. Role bindings need to be in place to allow system services to still function.

      • 1.7.1 - Do not admit privileged containers (Not Scored)
      • 1.7.2 - Do not admit containers wishing to share the host process ID namespace (Not Scored)
      • 1.7.3 - Do not admit containers wishing to share the host IPC namespace (Not Scored)
      • 1.7.4 - Do not admit containers wishing to share the host network namespace (Not Scored)
      • 1.7.5 - Do not admit containers with allowPrivilegeEscalation (Not Scored)
      • 1.7.6 - Do not admit root containers (Not Scored)
      • 1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)

      Audit

      • Verify that the cattle-system namespace exists:
      kubectl get ns |grep cattle
      • Verify that the roles exist:
      kubectl get role default-psp-role -n ingress-nginx
      kubectl get role default-psp-role -n cattle-system
      kubectl get clusterrole psp:restricted
      • Verify the bindings are set correctly:
      kubectl get rolebinding -n ingress-nginx default-psp-rolebinding
      kubectl get rolebinding -n cattle-system default-psp-rolebinding
      kubectl get clusterrolebinding psp:restricted
      • Verify the restricted PSP is present.
      kubectl get psp restricted

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      addons: |
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
      • Reconfigure the cluster:
      rke up --config cluster.yml

      3.1 - Rancher Management Control Plane Installation​

      3.1.1 - Disable the local cluster option​

      Profile Applicability

      • Level 2

      Description

      When deploying Rancher, disable the local cluster option on the Rancher Server.

      NOTE: This requires Rancher v2.1.2 or above.

      Rationale

      Having access to the local cluster from the Rancher UI is convenient for troubleshooting and debugging; however, if the local cluster is enabled in the Rancher UI, a user has access to all elements of the system, including the Rancher management server itself. Disabling the local cluster is a defense in depth measure and removes the possible attack vector from the Rancher UI and API.

      Audit

      • Verify the Rancher deployment has the --add-local=false option set.
      kubectl get deployment rancher -n cattle-system -o yaml |grep 'add-local'
      • In the Rancher UI go to Clusters in the Global view and verify that no local cluster is present.

      Remediation

      • Upgrade to Rancher v2.1.2 via the Helm chart. While performing the upgrade, provide the following installation flag:
      --set addLocal="false"

      3.1.2 - Enable Rancher Audit logging​

      Profile Applicability

      • Level 1

      Description

      Enable Rancher’s built-in audit logging capability.

      Rationale

      Tracking down what actions were performed by users in Rancher can provide insight during post mortems, and if monitored proactively can be used to quickly detect malicious actions.

      Audit

      • Verify that the audit log parameters were passed into the Rancher deployment.
      kubectl get deployment rancher -n cattle-system -o yaml | grep auditLog

      • Verify that the log is going to the appropriate destination, as set by auditLog.destination

        • sidecar:

          1. List pods:

            kubectl get pods -n cattle-system

          2. Tail logs:

            kubectl logs <pod> -n cattle-system -c rancher-audit-log

        • hostPath

          1. On the worker nodes running the Rancher pods, verify that the log files are being written to the destination indicated in auditlog.hostPath.

      Remediation

      Upgrade the Rancher server installation using Helm, and configure the audit log settings. The instructions for doing so can be found in the reference section below.

      Reference​

      3.2 - Rancher Management Control Plane Authentication​

      3.2.1 - Change the local administrator password from the default value​

      Profile Applicability

      • Level 1

      Description

      The local administrator password should be changed from the default.

      Rationale

      The default administrator password is common across all Rancher installations and should be changed immediately upon startup.

      Audit

      Attempt to login into the UI with the following credentials:

      • Username: admin
      • Password: admin

      The login attempt must not succeed.

      Remediation

      Change the password from admin to a password that meets the recommended password standards for your organization.

      3.2.2 - Configure an Identity Provider for Authentication​

      Profile Applicability

      • Level 1

      Description

      When running Rancher in a production environment, configure an identity provider for authentication.

      Rationale

      Rancher supports several authentication backends that are common in enterprises. It is recommended to tie Rancher into an external authentication system to simplify user and group access in the Rancher cluster. Doing so assures that access control follows the organization's change management process for user accounts.

      Audit

      • In the Rancher UI, select Global
      • Select Security
      • Select Authentication
      • Ensure the authentication provider for your environment is active and configured correctly

      Remediation

      Configure the appropriate authentication provider for your Rancher installation according to the documentation found at the link in the reference section below.

      Reference​

      3.3 - Rancher Management Control Plane RBAC​

      3.3.1 - Ensure that administrator privileges are only granted to those who require them​

      Profile Applicability

      • Level 1

      Description

      Restrict administrator access to only those responsible for managing and operating the Rancher server.

      Rationale

      The admin privilege level gives the user the highest level of access to the Rancher server and all attached clusters. This privilege should only be granted to a few people who are responsible for the availability and support of Rancher and the clusters that it manages.

      Audit

      The following script uses the Rancher API to show users with administrator privileges:

      #!/bin/bash
      for i in $(curl -sk -u 'token-<id>:<secret>' https://<RANCHER_URL>/v3/users|jq -r .data[].links.globalRoleBindings); do

      curl -sk -u 'token-<id>:<secret>' $i| jq '.data[] | "\(.userId) \(.globalRoleId)"'

      done

      The admin role should only be assigned to users that require administrative privileges. Any role that is not admin or user should be audited in the RBAC section of the UI to ensure that the privileges adhere to policies for global access.

      The Rancher server permits customization of the default global permissions. We recommend that auditors also review the policies of any custom global roles.

      Remediation

      Remove the admin role from any user that does not require administrative privileges.

      3.4 - Rancher Management Control Plane Configuration​

      3.4.1 - Ensure only approved node drivers are active​

      Profile Applicability

      • Level 1

      Description

      Ensure that node drivers that are not needed or approved are not active in the Rancher console.

      Rationale

      Node drivers are used to provision compute nodes in various cloud providers and local IaaS infrastructure. For convenience, popular cloud providers are enabled by default. If the organization does not intend to use these or does not allow users to provision resources in certain providers, the drivers should be disabled. This will prevent users from using Rancher resources to provision the nodes.

      Audit

      • In the Rancher UI select Global
      • Select Node Drivers
      • Review the list of node drivers that are in an Active state.

      Remediation

      If a disallowed node driver is active, visit the Node Drivers page under Global and disable it.

      Appendix A - Complete RKE cluster.yml Example​

      nodes:
      - address: 18.191.190.205
        internal_address: 172.31.24.213
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.203
        internal_address: 172.31.24.203
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.10
        internal_address: 172.31.24.244
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]

      services:
        kubelet:
          extra_args:
            streaming-connection-idle-timeout: "1800s"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"
        kube-api:
          pod_security_policy: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            repair-malformed-updates: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            experimental-encryption-provider-config: /etc/kubernetes/encryption.yaml
            admission-control-config-file: "/etc/kubernetes/admission.yaml"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            audit-policy-file: /etc/kubernetes/audit.yaml
          extra_binds:
            - "/var/log/kube-audit:/var/log/kube-audit"
        scheduler:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
      addons: |
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/self-assessment-guide-with-cis-v1.3-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/self-assessment-guide-with-cis-v1.3-benchmark.html index 15547b56d41..7ae46abf274 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/self-assessment-guide-with-cis-v1.3-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.1-hardening-guides/self-assessment-guide-with-cis-v1.3-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide v2.1 | Rancher Manager - + @@ -16,7 +16,7 @@ Result: Pass

      1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)​

      Audit

      docker inspect kube-scheduler | jq -e '.[0].Args[] | match("--address=127\\.0\\.0\\.1").string'

      Returned Value: --address=127.0.0.1 Result: Pass

      1.3 - Controller Manager​

      1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--terminated-pod-gc-threshold=\\d+").string'

      Returned Value: --terminated-pod-gc-threshold=1000 Result: Pass

      1.3.2 - Ensure that the --profiling argument is set to false (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--profiling=false").string'

      Returned Value: --profiling=false

      Result: Pass

      1.3.3 - Ensure that the --use-service-account-credentials argument is set to true (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--use-service-account-credentials=true").string'

      Returned Value: --use-service-account-credentials=true

      Result: Pass

      1.3.4 - Ensure that the --service-account-private-key-file argument is set as appropriate (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--service-account-private-key-file=.*").string'

      Returned Value: --service-account-private-key-file=/etc/kubernetes/ssl/kube-apiserver-key.pem

      Result: Pass

      1.3.5 - Ensure that the --root-ca-file argument is set as appropriate (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--root-ca-file=.*").string'

      Returned Value: --root-ca-file=/etc/kubernetes/ssl/kube-ca.pem

      Result: Pass

      1.3.6 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)​

      Notes

      RKE does not yet support certificate rotation. This feature is due for the 0.1.12 release of RKE.

      Audit

      docker inspect kube-apiserver | jq -e '.[0].Args[] | match("--feature-gates=.*(RotateKubeletServerCertificate=true).*").captures[].string'

      Returned Value: null

      Result: Fail

      1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)​

      Audit

      docker inspect kube-controller-manager | jq -e '.[0].Args[] | match("--address=127\\.0\\.0\\.1").string'

      Returned Value: --address=127.0.0.1

      Result: Pass

      1.4 - Configuration Files​

      1.4.1 - Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.2 - Ensure that the API server pod specification file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.3 - Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-controller-manager. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.4 - Ensure that the controller manager pod specification file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-controller-manager. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.5 - Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-scheduler. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.6 - Ensure that the scheduler pod specification file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kube-scheduler. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.7 - Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.8 - Ensure that the etcd pod specification file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      1.4.9 - Ensure that the Container Network Interface file permissions are set to 644 or more restrictive (Not Scored)​

      Notes

      This is a manual check.

      Audit (/var/lib/cni/networks/k8s-pod-network)

      ls -l /var/lib/cni/networks/k8s-pod-network/

      Returned Value:

      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.2
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.3
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.4
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.5
      -rw-r--r-- 1 root root   10 Nov  7 16:25 last_reserved_ip.0

      Audit (/etc/cni/net.d)

      ls -l /etc/cni/net.d/

      Returned Value:

      -rw-r--r-- 1 root root 1474 Nov  6 20:05 10-calico.conflist
      -rw------- 1 root root 2529 Nov  6 20:05 calico-kubeconfig

      Result: Pass

      1.4.10 - Ensure that the Container Network Interface file ownership is set to root:root (Not Scored)​

      Notes

      This is a manual check.

      Audit (/var/lib/cni/networks/k8s-pod-network)

      ls -l /var/lib/cni/networks/k8s-pod-network/

      Returned Value:

      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.2
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.3
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.4
      -rw-r--r-- 1 root root   64 Nov  6 20:05 10.42.0.5
      -rw-r--r-- 1 root root   10 Nov  7 16:25 last_reserved_ip.0

      Audit (/etc/cni/net.d)

      ls -l /etc/cni/net.d/

      Returned Value:

      -rw-r--r-- 1 root root 1474 Nov  6 20:05 10-calico.conflist
      -rw------- 1 root root 2529 Nov  6 20:05 calico-kubeconfig

      Result: Pass

      1.4.11 - Ensure that the etcd data directory permissions are set to 700 or more restrictive (Scored)​

      Notes

      Files underneath the data dir are permissioned 700

      ls -al /var/lib/etcd
      total 12
      drwxr-xr-x  3 root root 4096 Nov 14 17:06 .
      drwxr-xr-x 47 root root 4096 Nov 14 17:06 ..
      drwx------  4 root root 4096 Nov 14 17:06 member

      Audit

      stat -c %a /var/lib/etcd

      Returned Value: 755

      Result: Fail

      1.4.12 - Ensure that the etcd data directory ownership is set to etcd:etcd (Scored)​

      Notes

      The etcd container runs as the root user. The data directory and files are owned by root.

      Audit

      stat -c %U:%G /var/lib/etcd

      Returned Value: root:root

      Result: Fail

      1.4.13 - Ensure that the file permissions for admin.conf are set to 644 or more restrictive (Scored)​

      Notes

      RKE does not store the kubernetes default kubeconfig credentials file on the nodes. It's presented to user where RKE is run. We recommend that this kube_config_cluster.yml file be kept in secure store.

      Result: Pass (Not Applicable)

      1.4.14 - Ensure that ownership of admin.conf is set to root:root (Scored)​

      Notes

      RKE does not store the default kubectl config credentials file on the nodes. It presents credentials to the user when rke is first run, and only on the device where the user ran the command. Rancher Labs recommends that this kube_config_cluster.yml file be kept in secure store.

      Result: Pass (Not Applicable)

      1.4.15 - Ensure that the file permissions for scheduler.conf are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-scheduler.yaml

      Returned Value: 644

      Result: Pass

      1.4.16 - Ensure that the file ownership of scheduler.conf is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-scheduler.yaml

      Returned Value: root:root

      Result: Pass

      1.4.17 - Ensure that the file permissions for controller-manager.conf are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-controller-manager.yaml

      Returned Value: 644

      Result: Pass

      1.4.18 - Ensure that the file ownership of controller-manager.conf is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-controller-manager.yaml

      Returned Value: root:root

      Result: Pass

      1.5 - etcd​

      1.5.1 - Ensure that the --cert-file and --key-file arguments are set as appropriate (Scored)​

      Audit (--cert-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--cert-file=.*").string'

      Returned Value: --cert-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135.pem

      Audit (--key-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--key-file=.*").string'

      Returned Value: --key-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135-key.pem

      Result: Pass

      1.5.2 - Ensure that the --client-cert-auth argument is set to true (Scored)​

      Notes

      Setting "--client-cert-auth" is the equivalent of setting "--client-cert-auth=true".

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--client-cert-auth(=true)*").string'

      Returned Value: --client-cert-auth

      Result: Pass

      1.5.3 - Ensure that the --auto-tls argument is not set to true (Scored)​

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--auto-tls(?:(?!=false).*)").string'

      Returned Value: null

      Result: Pass

      1.5.4 - Ensure that the --peer-cert-file and --peer-key-file arguments are set as appropriate (Scored)​

      Audit (--peer-cert-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-cert-file=.*").string'

      Returned Value: --peer-cert-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135.pem

      Audit (--peer-key-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-key-file=.*").string'

      Returned Value: --peer-key-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135-key.pem

      Result: Pass

      1.5.5 - Ensure that the --peer-client-cert-auth argument is set to true (Scored)​

      Notes

      Setting --peer-client-cert-auth is the equivalent of setting --peer-client-cert-auth=true.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-client-cert-auth(=true)*").string'

      Returned Value: --client-cert-auth

      Result: Pass

      1.5.6 - Ensure that the --peer-auto-tls argument is not set to true (Scored)​

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-auto-tls(?:(?!=false).*)").string'

      Returned Value: null

      Result: Pass

      1.5.7 - Ensure that a unique Certificate Authority is used for etcd (Not Scored)​

      Notes

      RKE does not currently implement a separate CA for etcd certificates.

      --trusted-ca-file is set and different from the --client-ca-file used by kube-apiserver.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--trusted-ca-file=(?:(?!/etc/kubernetes/ssl/kube-ca.pem).*)").string'

      Returned Value: null

      Result: Fail

      1.6 - General Security Primitives​

      These "Not Scored" controls are implementation best practices. To ease the administrative burden, we recommend that you implement these best practices on your workload clusters by creating clusters with Rancher rather than using RKE alone.

      1.6.1 - Ensure that the cluster-admin role is only used where required (Not Scored)​

      Rancher has built in support for maintaining and enforcing Kubernetes RBAC on your workload clusters.

      Rancher has the ability integrate with external authentication sources (LDAP, SAML, AD…) allows easy access with unique credentials to your existing users or groups.

      1.6.2 - Create administrative boundaries between resources using namespaces (Not Scored)​

      With Rancher, users or groups can be assigned access to all clusters, a single cluster or a "Project" (a group of one or more namespaces in a cluster). This allows granular access control to cluster resources.

      1.6.3 - Create network segmentation using Network Policies (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate "Projects" (a group of one or more namespaces) in a cluster.

      See "Cluster Options" when creating a cluster with Rancher to turn on Network Isolation.

      1.6.4 - Ensure that the seccomp profile is set to docker/default in your pod definitions (Not Scored)​

      Since this requires the enabling of AllAlpha feature gates we would not recommend enabling this feature at the moment.

      1.6.5 - Apply security context to your pods and containers (Not Scored)​

      This practice does go against control 1.1.13, but we prefer using PodSecurityPolicy and allowing security context to be set over a blanket deny.

      Rancher allows users to set various Security Context options when launching pods via the GUI interface.

      1.6.6 - Configure image provenance using the ImagePolicyWebhook admission controller (Not Scored)​

      Image Policy Webhook requires a 3rd party service to enforce policy. This can be configured in the --admission-control-config-file. See the Host configuration section for the admission.yaml file.

      1.6.7 - Configure network policies as appropriate (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate projects (a group of one or more namespaces) within a cluster.

      See the Cluster Options section when creating a cluster with Rancher to turn on network isolation.

      1.6.8 - Place compensating controls in the form of PodSecurityPolicy (PSP) and RBAC for privileged container usage (Not Scored)​

      Section 1.7 of this guide shows how to add and configure a default "restricted" PSP based on controls.

      With Rancher you can create a centrally maintained "restricted" PSP and deploy it to all of the clusters that Rancher manages.

      1.7 - Pod Security Policies (PSP)​

      This RKE configuration has two Pod Security Policies.

      • default-psp: assigned to namespaces that require additional privileged access: kube-system, ingress-nginx and cattle-system.
      • restricted: This is the cluster default PSP and follows the best practices defined by controls in this section.

      1.7.1 - Do not admit privileged containers (Not Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.privileged}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.2 - Do not admit containers wishing to share the host process ID namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostPID}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.3 - Do not admit containers wishing to share the host IPC namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostIPC}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.4 - Do not admit containers wishing to share the host network namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostNetwork}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.5 - Do not admit containers with allowPrivilegeEscalation (Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.allowPrivilegeEscalation}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.6 - Do not admit containers whose processes run as root (Not Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.runAsUser.rule}' | grep "RunAsAny"

      Returned Value: null

      Result: Pass

      1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)​

      Notes

      The restricted PodSecurityPolicy (PSP) is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.requiredDropCapabilities}' | grep "NET_RAW"

      Returned Value: [NET_RAW]

      Result: Pass

      2 - Worker Node Security Configuration​

      2.1 - Kubelet​

      2.1.1 - Ensure that the --allow-privileged argument is set to false (Scored)​

      Notes

      The --allow-privileged argument is deprecated from Kubernetes v1.11, and the default setting is true with the intention that users should use PodSecurityPolicy settings to allow or prevent privileged containers.

      Our RKE configuration uses PodSecurityPolicy with a default policy to reject privileged containers.

      Result: Pass (Not Applicable)

      2.1.2 - Ensure that the --anonymous-auth argument is set to false (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--anonymous-auth=false").string'

      Returned Value: --anonymous-auth=false

      Result: Pass

      2.1.3 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)​

      Notes

      RKE currently runs the kubelet without the --authorization-mode flag.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--authorization-mode=Webhook").string'

      Returned Value: null

      Result: Fail

      2.1.4 - Ensure that the --client-ca-file argument is set as appropriate (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--client-ca-file=.*").string'

      Returned Value: --client-ca-file=/etc/kubernetes/ssl/kube-ca.pem

      Result: Pass

      2.1.5 - Ensure that the --read-only-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--read-only-port=0").string'

      Returned Value: --read-only-port=0

      Result: Pass

      2.1.6 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--streaming-connection-idle-timeout=.*").string'

      Returned Value: --streaming-connection-idle-timeout=1800s

      Result: Pass

      2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--protect-kernel-defaults=true").string'

      Returned Value: --protect-kernel-defaults=true

      Result: Pass

      2.1.8 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--make-iptables-util-chains=true").string'

      Returned Value: --make-iptables-util-chains=true

      Result: Pass

      2.1.9 - Ensure that the --hostname-override argument is not set (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--hostname-override=.*").string'

      Returned Value: --hostname-override=<ipv4 address>

      Result: Fail

      2.1.10 - Ensure that the --event-qps argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--event-qps=0").string'

      Returned Value: --event-qps=0

      Result: Pass

      2.1.11 - Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)​

      Notes

      RKE does not set these options and uses the kubelet's self generated certificates for TLS communication. These files are located in the default directory (/var/lib/kubelet/pki).

      Audit (--tls-cert-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cert-file=.*").string'

      Returned Value: null

      Audit (--tls-private-key-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-private-key-file=.*").string'

      Returned Value: null

      Result: Pass

      2.1.12 - Ensure that the --cadvisor-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--cadvisor-port=0").string'

      Returned Value: --cadvisor-port=0

      Result: Pass

      2.1.13 - Ensure that the --rotate-certificates argument is not set to false (Scored)​

      Notes

      RKE will enable certificate rotation in version 0.1.12.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--rotate-certificates=true").string'

      Returned Value: null

      Result: Fail

      2.1.14 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)​

      Notes

      RKE does not yet support certificate rotation. This feature is due for the 0.1.12 release of RKE.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--feature-gates=.*(RotateKubeletServerCertificate=true).*").captures[].string'

      Returned Value: null

      Result: Fail

      2.1.15 - Ensure that the kubelet only makes use of strong cryptographic ciphers (Not Scored)​

      Audit (Allowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value:

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value:

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value:

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_RSA_WITH_AES_256_GCM_SHA384

      Audit (Disallowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(CBC).*").captures[].string'

      Returned Value: null

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(RC4).*").captures[].string'

      Returned Value: null

      Result: Pass

      2.2 - Configuration Files​

      2.2.1 - Ensure that the permissions for kubelet.conf are set to 644 or more restrictive (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: 644

      Result: Pass

      2.2.2 - Ensure that the kubelet.conf file ownership is set to root:root (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: root:root

      Result: Pass

      2.2.3 - Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.4 - Ensure that the kubelet service file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.5 - Ensure that the proxy kubeconfig file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: 644

      Result: Pass

      2.2.6 - Ensure that the proxy kubeconfig file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: root:root

      Result: Pass

      2.2.7 - Ensure that the certificate authorities file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: 644

      Result: Pass

      2.2.8 - Ensure that the client certificate authorities file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: root:root

      Result: Pass

      2.2.9 - Ensure that the kubelet configuration file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.10 - Ensure that the kubelet configuration file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/hardening-guide-with-cis-v1.4-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/hardening-guide-with-cis-v1.4-benchmark.html index 50434e5f385..8cfe878d542 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/hardening-guide-with-cis-v1.4-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/hardening-guide-with-cis-v1.4-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide v2.2 | Rancher Manager - + @@ -13,7 +13,7 @@
      Version: v2.0-v2.4

      Hardening Guide v2.2

      This document provides prescriptive guidance for hardening a production installation of Rancher v2.2.x. It outlines the configurations and controls required to address Kubernetes benchmark controls from the Center for Information Security (CIS).

      This hardening guide describes how to secure the nodes in your cluster, and it is recommended to follow this guide before installing Kubernetes.

      This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

      Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
      Hardening Guide v2.2Rancher v2.2.xBenchmark v1.4.1, 1.4.0Kubernetes 1.13

      Click here to download a PDF version of this document

      For more detail about evaluating a hardened cluster against the official CIS benchmark, refer to the CIS Benchmark Rancher Self-Assessment Guide - Rancher v2.2.x.

      Profile Definitions​

      The following profile definitions agree with the CIS benchmarks for Kubernetes.

      A profile is a set of configurations that provide a certain amount of hardening. Generally, the more hardened an environment is, the more it affects performance.

      Level 1​

      Items in this profile intend to:

      • offer practical advice appropriate for the environment;
      • deliver an obvious security benefit; and
      • not alter the functionality or utility of the environment beyond an acceptable margin

      Level 2​

      Items in this profile extend the “Level 1” profile and exhibit one or more of the following characteristics:

      • are intended for use in environments or use cases where security is paramount
      • act as a defense in depth measure
      • may negatively impact the utility or performance of the technology

      1.1 - Rancher HA Kubernetes cluster host configuration​

      1.1.1 - Configure default sysctl settings on all hosts​

      Profile Applicability

      • Level 1

      Description

      Configure sysctl settings to match what the kubelet would set if allowed.

      Rationale

      We recommend that users launch the kubelet with the --protect-kernel-defaults option. The settings that the kubelet initially attempts to change can be set manually.

      This supports the following control:

      • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)

      Audit

      • Verify vm.overcommit_memory = 1
      sysctl vm.overcommit_memory
      • Verify kernel.panic = 10
      sysctl kernel.panic
      • Verify kernel.panic_on_oops = 1
      sysctl kernel.panic_on_oops

      Remediation

      • Set the following parameters in /etc/sysctl.conf on all nodes:
      vm.overcommit_memory=1
      kernel.panic=10
      kernel.panic_on_oops=1
      • Run sysctl -p to enable the settings.

      1.1.2 - Install the encryption provider configuration on all control plane nodes​

      Profile Applicability

      • Level 1

      Description

      Create a Kubernetes encryption configuration file on each of the RKE nodes that will be provisioned with the controlplane role:

      NOTE: The --experimental-encryption-provider-config flag in Kubernetes 1.13+ is actually --encryption-provider-config

      Rationale

      This configuration file will ensure that the Rancher RKE cluster encrypts secrets at rest, which Kubernetes does not do by default.

      This supports the following controls:

      • 1.1.34 - Ensure that the --experimental-encryption-provider-config argument is set as appropriate (Scored)
      • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)

      Audit

      On the control plane hosts for the Rancher HA cluster run:

      stat /opt/kubernetes/encryption.yaml

      Ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root
      • The file contains:
      apiVersion: apiserver.config.k8s.io/v1
      kind: EncryptionConfiguration
      resources:
        - resources:
          - secrets
          providers:
          - aescbc:
              keys:
              - name: key1
                secret: <32-byte base64 encoded string>
          - identity: {}

      Where aescbc is the key type, and secret is populated with a 32-byte base64 encoded string.

      Remediation

      • Generate a key and an empty configuration file:
      head -c 32 /dev/urandom | base64 -i -
      touch /opt/kubernetes/encryption.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /opt/kubernetes/encryption.yaml
      chmod 0600 /opt/kubernetes/encryption.yaml
      • Set the contents to:
      apiVersion: v1
      kind: EncryptionConfig
      resources:
        - resources:
          - secrets
          providers:
          - aescbc:
              keys:
              - name: key1
                secret: <32-byte base64 encoded string>
          - identity: {}

      Where secret is the 32-byte base64-encoded string generated in the first step.

      NOTE:

      Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

      1.1.3 - Install the audit log configuration on all control plane nodes.​

      Profile Applicability

      • Level 1

      Description

      Place the configuration file for Kubernetes audit logging on each of the control plane nodes in the cluster.

      Rationale

      The Kubernetes API has audit logging capability that is the best way to track actions in the cluster.

      This supports the following controls:

      • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
      • 1.1.16 - Ensure that the --audit-log-maxage argument is as appropriate (Scored)
      • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
      • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
      • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

      Audit

      On each control plane node, run:

      stat /opt/kubernetes/audit.yaml

      Ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root
      • The file contains:
      apiVersion: audit.k8s.io/v1beta1
      kind: Policy
      rules:
      - level: Metadata

      Remediation

      On nodes with the controlplane role:

      • Generate an empty configuration file:
      touch /opt/kubernetes/audit.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /opt/kubernetes/audit.yaml
      chmod 0600 /opt/kubernetes/audit.yaml
      • Set the contents to:
      apiVersion: audit.k8s.io/v1beta1
      kind: Policy
      rules:
      - level: Metadata

      NOTE:

      Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

      1.1.4 - Place Kubernetes event limit configuration on each control plane host​

      Profile Applicability

      • Level 1

      Description

      Place the configuration file for Kubernetes event limit configuration on each of the control plane nodes in the cluster.

      Rationale

      Set up the EventRateLimit admission control plugin to prevent clients from overwhelming the API server. The settings below are intended as an initial value and may need to be adjusted for larger clusters.

      This supports the following control:

      • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)

      Audit

      On nodes with the controlplane role run:

      stat /opt/kubernetes/admission.yaml
      stat /opt/kubernetes/event.yaml

      For each file, ensure that:

      • The file is present
      • The file mode is 0600
      • The file owner is root:root

      For admission.yaml ensure that the file contains:

      apiVersion: apiserver.k8s.io/v1alpha1
      kind: AdmissionConfiguration
      plugins:
      - name: EventRateLimit
        path: /opt/kubernetes/event.yaml

      For event.yaml ensure that the file contains:

      apiVersion: eventratelimit.admission.k8s.io/v1alpha1
      kind: Configuration
      limits:
      - type: Server
        qps: 5000
        burst: 20000

      Remediation

      On nodes with the controlplane role:

      • Generate an empty configuration file:
      touch /opt/kubernetes/admission.yaml
      touch /opt/kubernetes/event.yaml
      • Set the file ownership to root:root and the permissions to 0600
      chown root:root /opt/kubernetes/admission.yaml
      chown root:root /opt/kubernetes/event.yaml
      chmod 0600 /opt/kubernetes/admission.yaml
      chmod 0600 /opt/kubernetes/event.yaml
      • For admission.yaml set the contents to:
      apiVersion: apiserver.k8s.io/v1alpha1
      kind: AdmissionConfiguration
      plugins:
      - name: EventRateLimit
        path: /opt/kubernetes/event.yaml
      • For event.yaml set the contents to:
      apiVersion: eventratelimit.admission.k8s.io/v1alpha1
      kind: Configuration
      limits:
      - type: Server
        qps: 5000
        burst: 20000

      NOTE:

      Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

      2.1 - Rancher HA Kubernetes Cluster Configuration via RKE​

      (See Appendix A. for full RKE cluster.yml example)

      2.1.1 - Configure kubelet options​

      Profile Applicability

      • Level 1

      Description

      Ensure Kubelet options are configured to match CIS controls.

      Rationale

      To pass the following controls in the CIS benchmark, ensure the appropriate flags are passed to the Kubelet.

      • 2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
      • 2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)
      • 2.1.6 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)
      • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)
      • 2.1.8 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)
      • 2.1.10 - Ensure that the --event-qps argument is set to 0 (Scored)
      • 2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
      • 2.1.14 - Ensure that the Kubelet only makes use of Strong Cryptographic Ciphers (Not Scored)

      Audit

      Inspect the Kubelet containers on all hosts and verify that they are running with the following options:

      • --streaming-connection-idle-timeout=<duration greater than 0>
      • --authorization-mode=Webhook
      • --protect-kernel-defaults=true
      • --make-iptables-util-chains=true
      • --event-qps=0
      • --anonymous-auth=false
      • --feature-gates="RotateKubeletServerCertificate=true"
      • --tls-cipher-suites="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

      Remediation

      • Add the following to the RKE cluster.yml kubelet section under services:
      services:
        kubelet:
          extra_args:
            authorization-mode: "Webhook"
            streaming-connection-idle-timeout: "<duration>"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"
            anonymous-auth: "false"
            feature-gates: "RotateKubeletServerCertificate=true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

      Where <duration> is in a form like 1800s.

      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.2 - Configure kube-api options​

      Profile Applicability

      • Level 1

      Description

      Ensure the RKE configuration is set to deploy the kube-api service with the options required for controls.

      NOTE:

      Enabling the AlwaysPullImages admission control plugin can cause degraded performance due to overhead of always pulling images. Enabling the DenyEscalatingExec admission control plugin will prevent the 'Launch kubectl' functionality in the UI from working.

      Rationale

      To pass the following controls for the kube-api server ensure RKE configuration passes the appropriate options.

      • 1.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
      • 1.1.8 - Ensure that the --profiling argument is set to false (Scored)
      • 1.1.11 - Ensure that the admission control plugin AlwaysPullImages is set (Scored)
      • 1.1.12 - Ensure that the admission control plugin DenyEscalatingExec is set (Scored)
      • 1.1.14 - Ensure that the admission control plugin NamespaceLifecycle is set (Scored)
      • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
      • 1.1.16 - Ensure that the --audit-log-maxage argument is set as appropriate (Scored)
      • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
      • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
      • 1.1.23 - Ensure that the --service-account-lookup argument is set to true (Scored)
      • 1.1.24 - Ensure that the admission control plugin PodSecurityPolicy is set (Scored)
      • 1.1.30 Ensure that the API Server only makes use of Strong Cryptographic Ciphers (Not Scored)
      • 1.1.34 - Ensure that the --experimental-encryption-provider-config argument is set as appropriate (Scored)
      • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)
      • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)
      • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-apiserver containers:

        docker inspect kube-apiserver

      • Look for the following options in the command section of the output:

      --anonymous-auth=false
      --profiling=false
      --service-account-lookup=true
      --enable-admission-plugins= "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
      --encryption-provider-config=/opt/kubernetes/encryption.yaml
      --admission-control-config-file=/opt/kubernetes/admission.yaml
      --audit-log-path=/var/log/kube-audit/audit-log.json
      --audit-log-maxage=5
      --audit-log-maxbackup=5
      --audit-log-maxsize=100
      --audit-log-format=json
      --audit-policy-file=/opt/kubernetes/audit.yaml
      --tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
      • In the volume section of the output ensure the bind mount is present:
      /var/log/kube-audit:/var/log/kube-audit

      Remediation

      • In the RKE cluster.yml add the following directives to the kube-api section under services:
      services:
        kube-api:
          pod_security_policy: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            encryption-provider-config: /opt/kubernetes/encryption.yaml
            admission-control-config-file: "/opt/kubernetes/admission.yaml"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            audit-policy-file: /opt/kubernetes/audit.yaml
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/var/log/kube-audit:/var/log/kube-audit"
            - "/opt/kubernetes:/opt/kubernetes"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      NOTE:

      Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

      2.1.3 - Configure scheduler options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate options for the Kubernetes scheduling service.

      NOTE: Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

      Rationale

      To address the following controls on the CIS benchmark, the command line options should be set on the Kubernetes scheduler.

      • 1.2.1 - Ensure that the --profiling argument is set to false (Scored)
      • 1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role: inspect the kube-scheduler containers:
      docker inspect kube-scheduler
      • Verify the following options are set in the command section.
      --profiling=false
      --address=127.0.0.1

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        …
        scheduler:
          extra_args:
          profiling: "false"
          address: "127.0.0.1"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.4 - Configure controller options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate arguments on the Kubernetes controller manager.

      NOTE: Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

      Rationale

      To address the following controls the options need to be passed to the Kubernetes controller manager.

      • 1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)
      • 1.3.2 - Ensure that the --profiling argument is set to false (Scored)
      • 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
      • 1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-controller-manager container:
      docker inspect kube-controller-manager
      • Verify the following options are set in the command section:
      --terminated-pod-gc-threshold=1000
      --profiling=false
      --address=127.0.0.1
      --feature-gates="RotateKubeletServerCertificate=true"

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.5 - Configure addons and PSPs​

      Profile Applicability

      • Level 1

      Description

      Configure a restrictive pod security policy (PSP) as the default and create role bindings for system level services to use the less restrictive default PSP.

      Rationale

      To address the following controls, a restrictive default PSP needs to be applied as the default. Role bindings need to be in place to allow system services to still function.

      • 1.7.1 - Do not admit privileged containers (Not Scored)
      • 1.7.2 - Do not admit containers wishing to share the host process ID namespace (Not Scored)
      • 1.7.3 - Do not admit containers wishing to share the host IPC namespace (Not Scored)
      • 1.7.4 - Do not admit containers wishing to share the host network namespace (Not Scored)
      • 1.7.5 - Do not admit containers with allowPrivilegeEscalation (Not Scored)
      • 1.7.6 - Do not admit root containers (Not Scored)
      • 1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)

      Audit

      • Verify that the cattle-system namespace exists:
      kubectl get ns |grep cattle
      • Verify that the roles exist:
      kubectl get role default-psp-role -n ingress-nginx
      kubectl get role default-psp-role -n cattle-system
      kubectl get clusterrole psp:restricted
      • Verify the bindings are set correctly:
      kubectl get rolebinding -n ingress-nginx default-psp-rolebinding
      kubectl get rolebinding -n cattle-system default-psp-rolebinding
      kubectl get clusterrolebinding psp:restricted
      • Verify the restricted PSP is present.
      kubectl get psp restricted

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      addons: |
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
      • Reconfigure the cluster:
      rke up --config cluster.yml

      3.1 - Rancher Management Control Plane Installation​

      3.1.1 - Disable the local cluster option​

      Profile Applicability

      • Level 2

      Description

      When deploying Rancher, disable the local cluster option on the Rancher Server.

      NOTE: This requires Rancher v2.1.2 or above.

      Rationale

      Having access to the local cluster from the Rancher UI is convenient for troubleshooting and debugging; however, if the local cluster is enabled in the Rancher UI, a user has access to all elements of the system, including the Rancher management server itself. Disabling the local cluster is a defense in depth measure and removes the possible attack vector from the Rancher UI and API.

      Audit

      • Verify the Rancher deployment has the --add-local=false option set.
      kubectl get deployment rancher -n cattle-system -o yaml |grep 'add-local'
      • In the Rancher UI go to Clusters in the Global view and verify that no local cluster is present.

      Remediation

      • While upgrading or installing Rancher 2.2.x, provide the following flag:
      --set addLocal="false"

      3.1.2 - Enable Rancher Audit logging​

      Profile Applicability

      • Level 1

      Description

      Enable Rancher’s built-in audit logging capability.

      Rationale

      Tracking down what actions were performed by users in Rancher can provide insight during post mortems, and if monitored proactively can be used to quickly detect malicious actions.

      Audit

      • Verify that the audit log parameters were passed into the Rancher deployment.
      kubectl get deployment rancher -n cattle-system -o yaml | grep auditLog

      • Verify that the log is going to the appropriate destination, as set by auditLog.destination

        • sidecar:

          1. List pods:

            kubectl get pods -n cattle-system

          2. Tail logs:

            kubectl logs <pod> -n cattle-system -c rancher-audit-log

        • hostPath

          1. On the worker nodes running the Rancher pods, verify that the log files are being written to the destination indicated in auditlog.hostPath.

      Remediation

      Upgrade the Rancher server installation using Helm, and configure the audit log settings. The instructions for doing so can be found in the reference section below.

      Reference​

      3.2 - Rancher Management Control Plane Authentication​

      3.2.1 - Change the local administrator password from the default value​

      Profile Applicability

      • Level 1

      Description

      The local administrator password should be changed from the default.

      Rationale

      The default administrator password is common across all Rancher installations and should be changed immediately upon startup.

      Audit

      Attempt to login into the UI with the following credentials:

      • Username: admin
      • Password: admin

      The login attempt must not succeed.

      Remediation

      Change the password from admin to a password that meets the recommended password standards for your organization.

      3.2.2 - Configure an Identity Provider for Authentication​

      Profile Applicability

      • Level 1

      Description

      When running Rancher in a production environment, configure an identity provider for authentication.

      Rationale

      Rancher supports several authentication backends that are common in enterprises. It is recommended to tie Rancher into an external authentication system to simplify user and group access in the Rancher cluster. Doing so assures that access control follows the organization's change management process for user accounts.

      Audit

      • In the Rancher UI, select Global
      • Select Security
      • Select Authentication
      • Ensure the authentication provider for your environment is active and configured correctly

      Remediation

      Configure the appropriate authentication provider for your Rancher installation according to the documentation found at the link in the reference section below.

      Reference​

      3.3 - Rancher Management Control Plane RBAC​

      3.3.1 - Ensure that administrator privileges are only granted to those who require them​

      Profile Applicability

      • Level 1

      Description

      Restrict administrator access to only those responsible for managing and operating the Rancher server.

      Rationale

      The admin privilege level gives the user the highest level of access to the Rancher server and all attached clusters. This privilege should only be granted to a few people who are responsible for the availability and support of Rancher and the clusters that it manages.

      Audit

      The following script uses the Rancher API to show users with administrator privileges:

      #!/bin/bash
      for i in $(curl -sk -u 'token-<id>:<secret>' https://<RANCHER_URL>/v3/users|jq -r .data[].links.globalRoleBindings); do

      curl -sk -u 'token-<id>:<secret>' $i| jq '.data[] | "\(.userId) \(.globalRoleId)"'

      done

      The admin role should only be assigned to users that require administrative privileges. Any role that is not admin or user should be audited in the RBAC section of the UI to ensure that the privileges adhere to policies for global access.

      The Rancher server permits customization of the default global permissions. We recommend that auditors also review the policies of any custom global roles.

      Remediation

      Remove the admin role from any user that does not require administrative privileges.

      3.4 - Rancher Management Control Plane Configuration​

      3.4.1 - Ensure only approved node drivers are active​

      Profile Applicability

      • Level 1

      Description

      Ensure that node drivers that are not needed or approved are not active in the Rancher console.

      Rationale

      Node drivers are used to provision compute nodes in various cloud providers and local IaaS infrastructure. For convenience, popular cloud providers are enabled by default. If the organization does not intend to use these or does not allow users to provision resources in certain providers, the drivers should be disabled. This will prevent users from using Rancher resources to provision the nodes.

      Audit

      • In the Rancher UI select Global
      • Select Node Drivers
      • Review the list of node drivers that are in an Active state.

      Remediation

      If a disallowed node driver is active, visit the Node Drivers page under Global and disable it.

      Appendix A - Complete RKE cluster.yml Example​

      nodes:
      - address: 18.191.190.205
        internal_address: 172.31.24.213
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.203
        internal_address: 172.31.24.203
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.10
        internal_address: 172.31.24.244
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]

      services:
        kubelet:
          extra_args:
            streaming-connection-idle-timeout: "1800s"
            authorization-mode: "Webhook"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"
            anonymous-auth: "false"
            feature-gates: "RotateKubeletServerCertificate=true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        kube-api:
          pod_security_policy: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            encryption-provider-config: /opt/kubernetes/encryption.yaml
            admission-control-config-file: "/opt/kubernetes/admission.yaml"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            audit-policy-file: /opt/kubernetes/audit.yaml
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/var/log/kube-audit:/var/log/kube-audit"
            - "/opt/kubernetes:/opt/kubernetes"
        scheduler:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
      addons: |
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ingress-nginx
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/self-assessment-guide-with-cis-v1.4-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/self-assessment-guide-with-cis-v1.4-benchmark.html index cd628cb6eb8..011fd8e4e3d 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/self-assessment-guide-with-cis-v1.4-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.2-hardening-guides/self-assessment-guide-with-cis-v1.4-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide v2.2 | Rancher Manager - + @@ -22,7 +22,7 @@ Key file name may vary slightly, since it contains the IP of the etcd container. Certificate file name may vary slightly, since it contains the IP of the etcd container.

      Returned Value: --peer-cert-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135.pem

      Audit (--peer-key-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-key-file=.*").string'

      Note Key file name may vary slightly, since it contains the IP of the etcd container.

      Returned Value: --peer-key-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135-key.pem

      Result: Pass

      1.5.5 - Ensure that the --peer-client-cert-auth argument is set to true (Scored)​

      Notes

      Setting --peer-client-cert-auth is the equivalent of setting --peer-client-cert-auth=true.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-client-cert-auth(=true)*").string'

      Returned Value: --peer-client-cert-auth

      Result: Pass

      1.5.6 - Ensure that the --peer-auto-tls argument is not set to true (Scored)​

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-auto-tls(?:(?!=false).*)").string'

      Returned Value: null

      Result: Pass

      1.5.7 - Ensure that a unique Certificate Authority is used for etcd (Not Scored)​

      Mitigation

      RKE supports connecting to an external etcd cluster. This external cluster could be configured with its own discreet CA.

      Notes

      --trusted-ca-file is set and different from the --client-ca-file used by kube-apiserver.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--trusted-ca-file=(?:(?!/etc/kubernetes/ssl/kube-ca.pem).*)").string'

      Returned Value: null

      Result: Pass (See Mitigation)

      1.6 - General Security Primitives​

      These "Not Scored" controls are implementation best practices. To ease the administrative burden, we recommend that you implement these best practices on your workload clusters by creating clusters with Rancher rather than using RKE alone.

      1.6.1 - Ensure that the cluster-admin role is only used where required (Not Scored)​

      Rancher has built in support for maintaining and enforcing Kubernetes RBAC on your workload clusters.

      Rancher has the ability integrate with external authentication sources (LDAP, SAML, AD…) allows easy access with unique credentials to your existing users or groups.

      1.6.2 - Create administrative boundaries between resources using namespaces (Not Scored)​

      With Rancher, users or groups can be assigned access to all clusters, a single cluster or a "Project" (a group of one or more namespaces in a cluster). This allows granular access control to cluster resources.

      1.6.3 - Create network segmentation using Network Policies (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate "Projects" (a group of one or more namespaces) in a cluster.

      See "Cluster Options" when creating a cluster with Rancher to turn on Network Isolation.

      1.6.4 - Ensure that the seccomp profile is set to docker/default in your pod definitions (Not Scored)​

      Since this requires the enabling of AllAlpha feature gates we would not recommend enabling this feature at the moment.

      1.6.5 - Apply security context to your pods and containers (Not Scored)​

      This practice does go against control 1.1.13, but we prefer using a PodSecurityPolicy and allowing security context to be set over a blanket deny.

      Rancher allows users to set various Security Context options when launching pods via the GUI interface.

      1.6.6 - Configure image provenance using the ImagePolicyWebhook admission controller (Not Scored)​

      Image Policy Webhook requires a 3rd party service to enforce policy. This can be configured in the --admission-control-config-file. See the Host configuration section for the admission.yaml file.

      1.6.7 - Configure network policies as appropriate (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate projects (a group of one or more namespaces) within a cluster.

      See the Cluster Options section when creating a cluster with Rancher to turn on network isolation.

      1.6.8 - Place compensating controls in the form of PodSecurityPolicy (PSP) and RBAC for privileged container usage (Not Scored)​

      Section 1.7 of this guide shows how to add and configure a default "restricted" PSP based on controls.

      With Rancher you can create a centrally maintained "restricted" PSP and deploy it to all of the clusters that Rancher manages.

      1.7 - Pod Security Policies (PSP)​

      This RKE configuration has two Pod Security Policies.

      • default-psp: assigned to namespaces that require additional privileged access: kube-system, ingress-nginx and cattle-system.
      • restricted: This is the cluster default PSP and follows the best practices defined by controls in this section.

      1.7.1 - Do not admit privileged containers (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.privileged}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.2 - Do not admit containers wishing to share the host process ID namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostPID}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.3 - Do not admit containers wishing to share the host IPC namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostIPC}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.4 - Do not admit containers wishing to share the host network namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostNetwork}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.5 - Do not admit containers with allowPrivilegeEscalation (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.allowPrivilegeEscalation}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.6 - Do not admit containers whose processes run as root (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.runAsUser.rule}' | grep "RunAsAny"

      Returned Value: null

      Result: Pass

      1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.requiredDropCapabilities}' | grep "NET_RAW"

      Returned Value: [NET_RAW]

      Result: Pass

      2 - Worker Node Security Configuration​

      2.1 - Kubelet​

      2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--anonymous-auth=false").string'

      Returned Value: --anonymous-auth=false

      Result: Pass

      2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--authorization-mode=Webhook").string'

      Returned Value: --authorization-mode=Webhook

      Result: Pass

      2.1.3 - Ensure that the --client-ca-file argument is set as appropriate (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--client-ca-file=.*").string'

      Returned Value: --client-ca-file=/etc/kubernetes/ssl/kube-ca.pem

      Result: Pass

      2.1.4 - Ensure that the --read-only-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--read-only-port=0").string'

      Returned Value: --read-only-port=0

      Result: Pass

      2.1.5 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--streaming-connection-idle-timeout=.*").string'

      Returned Value: --streaming-connection-idle-timeout=1800s

      Result: Pass

      2.1.6 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--protect-kernel-defaults=true").string'

      Returned Value: --protect-kernel-defaults=true

      Result: Pass

      2.1.7 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--make-iptables-util-chains=true").string'

      Returned Value: --make-iptables-util-chains=true

      Result: Pass

      2.1.8 - Ensure that the --hostname-override argument is not set (Scored)​

      Notes This is used by most cloud providers. Not setting this is not practical in most cases.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--hostname-override=.*").string'

      Returned Value: --hostname-override=<ipv4 address>

      Result: Fail

      2.1.9 - Ensure that the --event-qps argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--event-qps=0").string'

      Returned Value: --event-qps=0

      Result: Pass

      2.1.10 - Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)​

      Notes

      RKE does not set these options and uses the kubelet's self generated certificates for TLS communication. These files are located in the default directory (/var/lib/kubelet/pki).

      Audit (--tls-cert-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cert-file=.*").string'

      Returned Value: null

      Audit (--tls-private-key-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-private-key-file=.*").string'

      Returned Value: null

      Result: Pass

      2.1.11 - Ensure that the --cadvisor-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--cadvisor-port=0").string'

      Returned Value: null

      Result: Pass

      2.1.12 - Ensure that the --rotate-certificates argument is not set to false (Scored)​

      Notes

      RKE handles certificate rotation through an external process.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--rotate-certificates=true").string'

      Returned Value: null

      Result: Pass (Not Applicable)

      2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--feature-gates=.*(RotateKubeletServerCertificate=true).*").captures[].string'

      Returned Value: RotateKubeletServerCertificate=true

      Result: Pass

      2.1.14 - Ensure that the kubelet only makes use of strong cryptographic ciphers (Not Scored)​

      Audit (Allowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_RSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_RSA_WITH_AES_128_GCM_SHA256

      Audit (Disallowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(CBC).*").captures[].string'

      Returned Value: null

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(RC4).*").captures[].string'

      Returned Value: null

      Result: Pass

      2.2 - Configuration Files​

      2.2.1 - Ensure that the permissions for kubelet.conf are set to 644 or more restrictive (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: 644

      Result: Pass

      2.2.2 - Ensure that the kubelet.conf file ownership is set to root:root (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: root:root

      Result: Pass

      2.2.3 - Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.4 - Ensure that the kubelet service file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.5 - Ensure that the proxy kubeconfig file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: 644

      Result: Pass

      2.2.6 - Ensure that the proxy kubeconfig file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: root:root

      Result: Pass

      2.2.7 - Ensure that the certificate authorities file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: 644

      Result: Pass

      2.2.8 - Ensure that the client certificate authorities file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: root:root

      Result: Pass

      2.2.9 - Ensure that the kubelet configuration file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      2.2.10 - Ensure that the kubelet configuration file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Pass (Not Applicable)

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-hardening-guide-with-cis-v1.4.1-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-hardening-guide-with-cis-v1.4.1-benchmark.html index 031c76da137..a12b60a7f85 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-hardening-guide-with-cis-v1.4.1-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-hardening-guide-with-cis-v1.4.1-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide v2.3 | Rancher Manager - + @@ -14,7 +14,7 @@ from the below command:

      ps -ef | grep etcd

      Run the below command (based on the etcd data directory found above). For example,

      stat -c %a /var/lib/rancher/etcd

      Verify that the permissions are 700 or more restrictive.

      Remediation

      Follow the steps as documented in 1.4.12 remediation.

      1.4.12 - Ensure that the etcd data directory ownership is set to etcd:etcd​

      Profile Applicability

      • Level 1

      Description

      Ensure that the etcd data directory ownership is set to etcd:etcd.

      Rationale

      etcd is a highly-available key-value store used by Kubernetes deployments for persistent storage of all of its REST API objects. This data directory should be protected from any unauthorized reads or writes. It should be owned by etcd:etcd.

      Audit

      On a etcd server node, get the etcd data directory, passed as an argument --data-dir, from the below command:

      ps -ef | grep etcd

      Run the below command (based on the etcd data directory found above). For example,

      stat -c %U:%G /var/lib/rancher/etcd

      Verify that the ownership is set to etcd:etcd.

      Remediation

      • On the etcd server node(s) add the etcd user:
      useradd etcd

      Record the uid/gid:

      id etcd
      • Add the following to the RKE cluster.yml etcd section under services:
      services:
        etcd:
          uid: <etcd user uid recorded previously>
          gid: <etcd user gid recorded previously>

      2.1 - Rancher HA Kubernetes Cluster Configuration via RKE​

      (See Appendix B. for full RKE cluster.yml example)

      2.1.1 - Configure kubelet options​

      Profile Applicability

      • Level 1

      Description

      Ensure Kubelet options are configured to match CIS controls.

      Rationale

      To pass the following controls in the CIS benchmark, ensure the appropriate flags are passed to the Kubelet.

      • 2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
      • 2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)
      • 2.1.6 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)
      • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)
      • 2.1.8 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)
      • 2.1.10 - Ensure that the --event-qps argument is set to 0 (Scored)
      • 2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
      • 2.1.14 - Ensure that the Kubelet only makes use of Strong Cryptographic Ciphers (Not Scored)

      Audit

      Inspect the Kubelet containers on all hosts and verify that they are running with the following options:

      • --streaming-connection-idle-timeout=<duration greater than 0>
      • --authorization-mode=Webhook
      • --protect-kernel-defaults=true
      • --make-iptables-util-chains=true
      • --event-qps=0
      • --anonymous-auth=false
      • --feature-gates="RotateKubeletServerCertificate=true"
      • --tls-cipher-suites="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

      Remediation

      • Add the following to the RKE cluster.yml kubelet section under services:
      services:
        kubelet:
          extra_args:
            authorization-mode: "Webhook"
            streaming-connection-idle-timeout: "<duration>"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"
            anonymous-auth: "false"
            feature-gates: "RotateKubeletServerCertificate=true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

      Where <duration> is in a form like 1800s.

      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.2 - Configure kube-api options​

      Profile Applicability

      • Level 1

      Description

      Ensure the RKE configuration is set to deploy the kube-api service with the options required for controls.

      NOTE:

      Enabling the AlwaysPullImages admission control plugin can cause degraded performance due to overhead of always pulling images. Enabling the DenyEscalatingExec admission control plugin will prevent the 'Launch kubectl' functionality in the UI from working.

      Rationale

      To pass the following controls for the kube-api server ensure RKE configuration passes the appropriate options.

      • 1.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
      • 1.1.8 - Ensure that the --profiling argument is set to false (Scored)
      • 1.1.11 - Ensure that the admission control plugin AlwaysPullImages is set (Scored)
      • 1.1.12 - Ensure that the admission control plugin DenyEscalatingExec is set (Scored)
      • 1.1.14 - Ensure that the admission control plugin NamespaceLifecycle is set (Scored)
      • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
      • 1.1.16 - Ensure that the --audit-log-maxage argument is set as appropriate (Scored)
      • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
      • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
      • 1.1.23 - Ensure that the --service-account-lookup argument is set to true (Scored)
      • 1.1.24 - Ensure that the admission control plugin PodSecurityPolicy is set (Scored)
      • 1.1.30 Ensure that the API Server only makes use of Strong Cryptographic Ciphers (Not Scored)
      • 1.1.34 - Ensure that the --experimental-encryption-provider-config argument is set as appropriate (Scored)
      • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)
      • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)
      • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-apiserver containers:

        docker inspect kube-apiserver

      • Look for the following options in the command section of the output:

      --anonymous-auth=false
      --profiling=false
      --service-account-lookup=true
      --enable-admission-plugins= "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
      --encryption-provider-config=/opt/kubernetes/encryption.yaml
      --admission-control-config-file=/opt/kubernetes/admission.yaml
      --audit-log-path=/var/log/kube-audit/audit-log.json
      --audit-log-maxage=5
      --audit-log-maxbackup=5
      --audit-log-maxsize=100
      --audit-log-format=json
      --audit-policy-file=/opt/kubernetes/audit.yaml
      --tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
      • In the volume section of the output ensure the bind mount is present:
      /var/log/kube-audit:/var/log/kube-audit

      Remediation

      • In the RKE cluster.yml add the following directives to the kube-api section under services:
      services:
        kube-api:
          pod_security_policy: true
          event_rate_limit:
            enabled: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/opt/kubernetes:/opt/kubernetes"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      NOTE:

      Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

      2.1.3 - Configure scheduler options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate options for the Kubernetes scheduling service.

      NOTE: Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

      Rationale

      To address the following controls on the CIS benchmark, the command line options should be set on the Kubernetes scheduler.

      • 1.2.1 - Ensure that the --profiling argument is set to false (Scored)
      • 1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role: inspect the kube-scheduler containers:
      docker inspect kube-scheduler
      • Verify the following options are set in the command section.
      --profiling=false
      --address=127.0.0.1

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        …
        scheduler:
          extra_args:
          profiling: "false"
          address: "127.0.0.1"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.4 - Configure controller options​

      Profile Applicability

      • Level 1

      Description

      Set the appropriate arguments on the Kubernetes controller manager.

      5*NOTE:** Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

      Rationale

      To address the following controls the options need to be passed to the Kubernetes controller manager.

      • 1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)
      • 1.3.2 - Ensure that the --profiling argument is set to false (Scored)
      • 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
      • 1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

      Audit

      • On nodes with the controlplane role inspect the kube-controller-manager container:
      docker inspect kube-controller-manager
      • Verify the following options are set in the command section:
      --terminated-pod-gc-threshold=1000
      --profiling=false
      --address=127.0.0.1
      --feature-gates="RotateKubeletServerCertificate=true"

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      services:
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
      • Reconfigure the cluster:
      rke up --config cluster.yml

      2.1.5 - Configure addons and PSPs​

      Profile Applicability

      • Level 1

      Description

      Configure a restrictive pod security policy (PSP) as the default and create role bindings for system level services to use the less restrictive default PSP.

      Rationale

      To address the following controls, a restrictive default PSP needs to be applied as the default. Role bindings need to be in place to allow system services to still function.

      • 1.7.1 - Do not admit privileged containers (Not Scored)
      • 1.7.2 - Do not admit containers wishing to share the host process ID namespace (Not Scored)
      • 1.7.3 - Do not admit containers wishing to share the host IPC namespace (Not Scored)
      • 1.7.4 - Do not admit containers wishing to share the host network namespace (Not Scored)
      • 1.7.5 - Do not admit containers with allowPrivilegeEscalation (Not Scored)
      • 1.7.6 - Do not admit root containers (Not Scored)
      • 1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)

      Audit

      • Verify that the cattle-system namespace exists:
      kubectl get ns |grep cattle
      • Verify that the roles exist:
      kubectl get role default-psp-role -n ingress-nginx
      kubectl get role default-psp-role -n cattle-system
      kubectl get clusterrole psp:restricted
      • Verify the bindings are set correctly:
      kubectl get rolebinding -n ingress-nginx default-psp-rolebinding
      kubectl get rolebinding -n cattle-system default-psp-rolebinding
      kubectl get clusterrolebinding psp:restricted
      • Verify the restricted PSP is present.
      kubectl get psp restricted

      Remediation

      • In the RKE cluster.yml file ensure the following options are set:
      addons: |
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
      • Reconfigure the cluster:
      rke up --config cluster.yml

      3.1 - Rancher Management Control Plane Installation​

      3.1.1 - Disable the local cluster option​

      Profile Applicability

      • Level 2

      Description

      When deploying Rancher, disable the local cluster option on the Rancher Server.

      NOTE: This requires Rancher v2.1.2 or above.

      Rationale

      Having access to the local cluster from the Rancher UI is convenient for troubleshooting and debugging; however, if the local cluster is enabled in the Rancher UI, a user has access to all elements of the system, including the Rancher management server itself. Disabling the local cluster is a defense in depth measure and removes the possible attack vector from the Rancher UI and API.

      Audit

      • Verify the Rancher deployment has the --add-local=false option set.
      kubectl get deployment rancher -n cattle-system -o yaml |grep 'add-local'
      • In the Rancher UI go to Clusters in the Global view and verify that no local cluster is present.

      Remediation

      • While upgrading or installing Rancher 2.3.x, provide the following flag:
      --set addLocal="false"

      3.1.2 - Enable Rancher Audit logging​

      Profile Applicability

      • Level 1

      Description

      Enable Rancher’s built-in audit logging capability.

      Rationale

      Tracking down what actions were performed by users in Rancher can provide insight during post mortems, and if monitored proactively can be used to quickly detect malicious actions.

      Audit

      • Verify that the audit log parameters were passed into the Rancher deployment.
      kubectl get deployment rancher -n cattle-system -o yaml | grep auditLog

      • Verify that the log is going to the appropriate destination, as set by auditLog.destination

        • sidecar:

          1. List pods:

            kubectl get pods -n cattle-system

          2. Tail logs:

            kubectl logs <pod> -n cattle-system -c rancher-audit-log

        • hostPath

          1. On the worker nodes running the Rancher pods, verify that the log files are being written to the destination indicated in auditlog.hostPath.

      Remediation

      Upgrade the Rancher server installation using Helm, and configure the audit log settings. The instructions for doing so can be found in the reference section below.

      Reference​

      3.2 - Rancher Management Control Plane Authentication​

      3.2.1 - Change the local administrator password from the default value​

      Profile Applicability

      • Level 1

      Description

      The local administrator password should be changed from the default.

      Rationale

      The default administrator password is common across all Rancher installations and should be changed immediately upon startup.

      Audit

      Attempt to login into the UI with the following credentials:

      • Username: admin
      • Password: admin

      The login attempt must not succeed.

      Remediation

      Change the password from admin to a password that meets the recommended password standards for your organization.

      3.2.2 - Configure an Identity Provider for Authentication​

      Profile Applicability

      • Level 1

      Description

      When running Rancher in a production environment, configure an identity provider for authentication.

      Rationale

      Rancher supports several authentication backends that are common in enterprises. It is recommended to tie Rancher into an external authentication system to simplify user and group access in the Rancher cluster. Doing so assures that access control follows the organization's change management process for user accounts.

      Audit

      • In the Rancher UI, select Global
      • Select Security
      • Select Authentication
      • Ensure the authentication provider for your environment is active and configured correctly

      Remediation

      Configure the appropriate authentication provider for your Rancher installation according to the documentation found at the link in the reference section below.

      Reference​

      3.3 - Rancher Management Control Plane RBAC​

      3.3.1 - Ensure that administrator privileges are only granted to those who require them​

      Profile Applicability

      • Level 1

      Description

      Restrict administrator access to only those responsible for managing and operating the Rancher server.

      Rationale

      The admin privilege level gives the user the highest level of access to the Rancher server and all attached clusters. This privilege should only be granted to a few people who are responsible for the availability and support of Rancher and the clusters that it manages.

      Audit

      The following script uses the Rancher API to show users with administrator privileges:

      #!/bin/bash
      for i in $(curl -sk -u 'token-<id>:<secret>' https://<RANCHER_URL>/v3/users|jq -r .data[].links.globalRoleBindings); do

      curl -sk -u 'token-<id>:<secret>' $i| jq '.data[] | "\(.userId) \(.globalRoleId)"'

      done

      The admin role should only be assigned to users that require administrative privileges. Any role that is not admin or user should be audited in the RBAC section of the UI to ensure that the privileges adhere to policies for global access.

      The Rancher server permits customization of the default global permissions. We recommend that auditors also review the policies of any custom global roles.

      Remediation

      Remove the admin role from any user that does not require administrative privileges.

      3.4 - Rancher Management Control Plane Configuration​

      3.4.1 - Ensure only approved node drivers are active​

      Profile Applicability

      • Level 1

      Description

      Ensure that node drivers that are not needed or approved are not active in the Rancher console.

      Rationale

      Node drivers are used to provision compute nodes in various cloud providers and local IaaS infrastructure. For convenience, popular cloud providers are enabled by default. If the organization does not intend to use these or does not allow users to provision resources in certain providers, the drivers should be disabled. This will prevent users from using Rancher resources to provision the nodes.

      Audit

      • In the Rancher UI select Global
      • Select Node Drivers
      • Review the list of node drivers that are in an Active state.

      Remediation

      If a disallowed node driver is active, visit the Node Drivers page under Global and disable it.

      Appendix A - Complete ubuntu cloud-config Example​

      cloud-config file to automate hardening manual steps on nodes deployment.

      #cloud-config
      bootcmd:
      - apt-get update
      - apt-get install -y apt-transport-https
      apt:
        sources:
          docker:
            source: "deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable"
            keyid: 0EBFCD88
      packages:
      - [docker-ce, '5:19.03.5~3-0~ubuntu-bionic']
      - jq
      write_files:
      # 1.1.1 - Configure default sysctl settings on all hosts
      - path: /etc/sysctl.d/90-kubelet.conf
        owner: root:root
        permissions: '0644'
        content: |
          vm.overcommit_memory=1
          vm.panic_on_oom=0
          kernel.panic=10
          kernel.panic_on_oops=1
          kernel.keys.root_maxkeys=1000000
          kernel.keys.root_maxbytes=25000000
      # 1.1.2 encription provider
      - path: /opt/kubernetes/encryption.yaml
        owner: root:root
        permissions: '0600'
        content: |
          apiVersion: apiserver.config.k8s.io/v1
          kind: EncryptionConfiguration
          resources:
            - resources:
              - secrets
              providers:
              - aescbc:
                  keys:
                  - name: key1
                    secret: QRCexFindur3dzS0P/UmHs5xA6sKu58RbtWOQFarfh4=
              - identity: {}
      # 1.1.3 audit log
      - path: /opt/kubernetes/audit.yaml
        owner: root:root
        permissions: '0600'
        content: |
          apiVersion: audit.k8s.io/v1beta1
          kind: Policy
          rules:
          - level: Metadata
      # 1.1.4 event limit
      - path: /opt/kubernetes/admission.yaml
        owner: root:root
        permissions: '0600'
        content: |
          apiVersion: apiserver.k8s.io/v1alpha1
          kind: AdmissionConfiguration
          plugins:
          - name: EventRateLimit
            path: /opt/kubernetes/event.yaml
      - path: /opt/kubernetes/event.yaml
        owner: root:root
        permissions: '0600'
        content: |
          apiVersion: eventratelimit.admission.k8s.io/v1alpha1
          kind: Configuration
          limits:
          - type: Server
            qps: 5000
            burst: 20000
      # 1.4.12 etcd user
      groups:
        - etcd
      users:
        - default
        - name: etcd
          gecos: Etcd user
          primary_group: etcd
          homedir: /var/lib/etcd
      # 1.4.11 etcd data dir
      runcmd:
        - chmod 0700 /var/lib/etcd
        - usermod -G docker -a ubuntu
        - sysctl -p /etc/sysctl.d/90-kubelet.conf

      Appendix B - Complete RKE cluster.yml Example​

      nodes:
      - address: 18.191.190.205
        internal_address: 172.31.24.213
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.203
        internal_address: 172.31.24.203
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]
      - address: 18.191.190.10
        internal_address: 172.31.24.244
        user: ubuntu
        role: [ "controlplane", "etcd", "worker" ]

      services:
        kubelet:
          extra_args:
            streaming-connection-idle-timeout: "1800s"
            authorization-mode: "Webhook"
            protect-kernel-defaults: "true"
            make-iptables-util-chains: "true"
            event-qps: "0"
            anonymous-auth: "false"
            feature-gates: "RotateKubeletServerCertificate=true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
            generate_serving_certificate: true
        kube-api:
          pod_security_policy: true
          event_rate_limit:
            enabled: true
          extra_args:
            anonymous-auth: "false"
            profiling: "false"
            service-account-lookup: "true"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            audit-log-path: "/var/log/kube-audit/audit-log.json"
            audit-log-maxage: "5"
            audit-log-maxbackup: "5"
            audit-log-maxsize: "100"
            audit-log-format: "json"
            audit-policy-file: /opt/kubernetes/audit.yaml
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/opt/kubernetes:/opt/kubernetes"
        scheduler:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
        services:
          etcd:
            uid: 1001
            gid: 1001
      addons: |
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ingress-nginx
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: extensions/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated

      Appendix C - Complete RKE Template Example​

      #
      # Cluster Config
      #
      default_pod_security_policy_template_id: restricted
      docker_root_dir: /var/lib/docker
      enable_cluster_alerting: false
      enable_cluster_monitoring: false
      enable_network_policy: false
      #
      # Rancher Config
      #
      rancher_kubernetes_engine_config:
        addon_job_timeout: 30
        ignore_docker_version: true
      #
      #   If you are using calico on AWS
      #
      #    network:
      #      plugin: calico
      #      calico_network_provider:
      #        cloud_provider: aws
      #
      # # To specify flannel interface
      #
      #    network:
      #      plugin: flannel
      #      flannel_network_provider:
      #      iface: eth1
      #
      # # To specify flannel interface for canal plugin
      #
      #    network:
      #      plugin: canal
      #      canal_network_provider:
      #        iface: eth1
      #
        network:
          plugin: canal
      #
      #    services:
      #      kube-api:
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kube-controller:
      #        cluster_cidr: 10.42.0.0/16
      #        service_cluster_ip_range: 10.43.0.0/16
      #      kubelet:
      #        cluster_domain: cluster.local
      #        cluster_dns_server: 10.43.0.10
      #
        services:
          etcd:
            backup_config:
              enabled: false
              interval_hours: 12
              retention: 6
              safe_timestamp: false
            creation: 12h
            extra_args:
              election-timeout: '5000'
              heartbeat-interval: '500'
            gid: 1001
            retention: 72h
            snapshot: false
            uid: 1001
          kube_api:
            always_pull_images: false
            event_rate_limit:
              enabled: true
            extra_args:
              anonymous-auth: 'false'
              audit-log-format: json
              audit-log-maxage: '5'
              audit-log-maxbackup: '5'
              audit-log-maxsize: '100'
              audit-log-path: /var/log/kube-audit/audit-log.json
              enable-admission-plugins: >-
                ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy
              profiling: 'false'
              service-account-lookup: 'true'
              tls-cipher-suites: >-
                TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
            extra_binds:
              - '/opt/kubernetes:/opt/kubernetes'
            pod_security_policy: true
            service_node_port_range: 30000-32767
          kube_controller:
            extra_args:
              address: 127.0.0.1
              feature-gates: RotateKubeletServerCertificate=true
              profiling: 'false'
              terminated-pod-gc-threshold: '1000'
          kubelet:
            extra_args:
              anonymous-auth: 'false'
              event-qps: '0'
              feature-gates: RotateKubeletServerCertificate=true
              make-iptables-util-chains: 'true'
              protect-kernel-defaults: 'true'
              streaming-connection-idle-timeout: 1800s
              tls-cipher-suites: >-
                TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
            fail_swap_on: false
          scheduler:
            extra_args:
              address: 127.0.0.1
              profiling: 'false'
        ssh_agent_auth: false
      windows_prefered_cluster: false
      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-self-assessment-guide-with-cis-v1.4.1-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-self-assessment-guide-with-cis-v1.4.1-benchmark.html index 9568d8bca06..dda21023bdf 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-self-assessment-guide-with-cis-v1.4.1-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.0-self-assessment-guide-with-cis-v1.4.1-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide v2.3 | Rancher Manager - + @@ -18,7 +18,7 @@ Key file name may vary slightly, since it contains the IP of the etcd container. Certificate file name may vary slightly, since it contains the IP of the etcd container.

      Returned Value: --peer-cert-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135.pem

      Audit (--peer-key-file)

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-key-file=.*").string'

      Note Key file name may vary slightly, since it contains the IP of the etcd container.

      Returned Value: --peer-key-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135-key.pem

      Result: Pass

      1.5.5 - Ensure that the --peer-client-cert-auth argument is set to true (Scored)​

      Notes

      Setting --peer-client-cert-auth is the equivalent of setting --peer-client-cert-auth=true.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-client-cert-auth(=true)*").string'

      Returned Value: --peer-client-cert-auth

      Result: Pass

      1.5.6 - Ensure that the --peer-auto-tls argument is not set to true (Scored)​

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--peer-auto-tls(?:(?!=false).*)").string'

      Returned Value: null

      Result: Pass

      1.5.7 - Ensure that a unique Certificate Authority is used for etcd (Not Scored)​

      Mitigation

      RKE supports connecting to an external etcd cluster. This external cluster could be configured with its own discreet CA.

      Notes

      --trusted-ca-file is set and different from the --client-ca-file used by kube-apiserver.

      Audit

      docker inspect etcd | jq -e '.[0].Args[] | match("--trusted-ca-file=(?:(?!/etc/kubernetes/ssl/kube-ca.pem).*)").string'

      Returned Value: null

      Result: Pass (See Mitigation)

      1.6 - General Security Primitives​

      These "Not Scored" controls are implementation best practices. To ease the administrative burden, we recommend that you implement these best practices on your workload clusters by creating clusters with Rancher rather than using RKE alone.

      1.6.1 - Ensure that the cluster-admin role is only used where required (Not Scored)​

      Rancher has built in support for maintaining and enforcing Kubernetes RBAC on your workload clusters.

      Rancher has the ability integrate with external authentication sources (LDAP, SAML, AD…) allows easy access with unique credentials to your existing users or groups.

      1.6.2 - Create administrative boundaries between resources using namespaces (Not Scored)​

      With Rancher, users or groups can be assigned access to all clusters, a single cluster or a "Project" (a group of one or more namespaces in a cluster). This allows granular access control to cluster resources.

      1.6.3 - Create network segmentation using Network Policies (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate "Projects" (a group of one or more namespaces) in a cluster.

      See "Cluster Options" when creating a cluster with Rancher to turn on Network Isolation.

      1.6.4 - Ensure that the seccomp profile is set to docker/default in your pod definitions (Not Scored)​

      Since this requires the enabling of AllAlpha feature gates we would not recommend enabling this feature at the moment.

      1.6.5 - Apply security context to your pods and containers (Not Scored)​

      This practice does go against control 1.1.13, but we prefer using a PodSecurityPolicy and allowing security context to be set over a blanket deny.

      Rancher allows users to set various Security Context options when launching pods via the GUI interface.

      1.6.6 - Configure image provenance using the ImagePolicyWebhook admission controller (Not Scored)​

      Image Policy Webhook requires a 3rd party service to enforce policy. This can be configured in the --admission-control-config-file. See the Host configuration section for the admission.yaml file.

      1.6.7 - Configure network policies as appropriate (Not Scored)​

      Rancher can (optionally) automatically create Network Policies to isolate projects (a group of one or more namespaces) within a cluster.

      See the Cluster Options section when creating a cluster with Rancher to turn on network isolation.

      1.6.8 - Place compensating controls in the form of PodSecurityPolicy (PSP) and RBAC for privileged container usage (Not Scored)​

      Section 1.7 of this guide shows how to add and configure a default "restricted" PSP based on controls.

      With Rancher you can create a centrally maintained "restricted" PSP and deploy it to all of the clusters that Rancher manages.

      1.7 - Pod Security Policies (PSP)​

      This RKE configuration has two Pod Security Policies.

      • default-psp: assigned to namespaces that require additional privileged access: kube-system, ingress-nginx and cattle-system.
      • restricted: This is the cluster default PSP and follows the best practices defined by controls in this section.

      1.7.1 - Do not admit privileged containers (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.privileged}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.2 - Do not admit containers wishing to share the host process ID namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostPID}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.3 - Do not admit containers wishing to share the host IPC namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostIPC}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.4 - Do not admit containers wishing to share the host network namespace (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.hostNetwork}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.5 - Do not admit containers with allowPrivilegeEscalation (Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.allowPrivilegeEscalation}' | grep "true"

      Returned Value: null

      Result: Pass

      1.7.6 - Do not admit containers whose processes run as root (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.runAsUser.rule}' | grep "RunAsAny"

      Returned Value: null

      Result: Pass

      1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)​

      Notes

      The restricted PodSecurityPolicy is available to all ServiceAccounts.

      Audit

      kubectl get psp restricted -o jsonpath='{.spec.requiredDropCapabilities}' | grep "NET_RAW"

      Returned Value: [NET_RAW]

      Result: Pass

      2 - Worker Node Security Configuration​

      2.1 - Kubelet​

      2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--anonymous-auth=false").string'

      Returned Value: --anonymous-auth=false

      Result: Pass

      2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--authorization-mode=Webhook").string'

      Returned Value: --authorization-mode=Webhook

      Result: Pass

      2.1.3 - Ensure that the --client-ca-file argument is set as appropriate (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--client-ca-file=.*").string'

      Returned Value: --client-ca-file=/etc/kubernetes/ssl/kube-ca.pem

      Result: Pass

      2.1.4 - Ensure that the --read-only-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--read-only-port=0").string'

      Returned Value: --read-only-port=0

      Result: Pass

      2.1.5 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--streaming-connection-idle-timeout=.*").string'

      Returned Value: --streaming-connection-idle-timeout=1800s

      Result: Pass

      2.1.6 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--protect-kernel-defaults=true").string'

      Returned Value: --protect-kernel-defaults=true

      Result: Pass

      2.1.7 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--make-iptables-util-chains=true").string'

      Returned Value: --make-iptables-util-chains=true

      Result: Pass

      2.1.8 - Ensure that the --hostname-override argument is not set (Scored)​

      Notes This is used by most cloud providers. Not setting this is not practical in most cases.

      Result: Not Applicable

      2.1.9 - Ensure that the --event-qps argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--event-qps=0").string'

      Returned Value: --event-qps=0

      Result: Pass

      2.1.10 - Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)​

      Notes

      RKE does not set these options and uses the kubelet's self generated certificates for TLS communication. These files are located in the default directory (/var/lib/kubelet/pki).

      Audit (--tls-cert-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cert-file=.*").string'

      Returned Value: null

      Audit (--tls-private-key-file)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-private-key-file=.*").string'

      Returned Value: null

      Result: Pass

      2.1.11 - Ensure that the --cadvisor-port argument is set to 0 (Scored)​

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--cadvisor-port=0").string'

      Returned Value: null

      Result: Pass

      2.1.12 - Ensure that the --rotate-certificates argument is not set to false (Scored)​

      Notes

      RKE handles certificate rotation through an external process.

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--rotate-certificates=true").string'

      Returned Value: null

      Result: Not Applicable

      2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)​

      Notes

      RKE handles certificate rotation through an external process.

      Result: Not Applicable

      2.1.14 - Ensure that the kubelet only makes use of strong cryptographic ciphers (Not Scored)​

      Audit (Allowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305).*").captures[].string'

      Returned Value: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

      Returned Value: TLS_RSA_WITH_AES_256_GCM_SHA384

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

      Returned Value: TLS_RSA_WITH_AES_128_GCM_SHA256

      Audit (Disallowed Ciphers)

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(CBC).*").captures[].string'

      Returned Value: null

      Audit

      docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(RC4).*").captures[].string'

      Returned Value: null

      Result: Pass

      2.2 - Configuration Files​

      2.2.1 - Ensure that the permissions for kubelet.conf are set to 644 or more restrictive (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: 644

      Result: Pass

      2.2.2 - Ensure that the kubelet.conf file ownership is set to root:root (Scored)​

      Notes

      This is the value of the --kubeconfig option.

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-node.yaml

      Returned Value: root:root

      Result: Pass

      2.2.3 - Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Not Applicable

      2.2.4 - Ensure that the kubelet service file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Not Applicable

      2.2.5 - Ensure that the proxy kubeconfig file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: 644

      Result: Pass

      2.2.6 - Ensure that the proxy kubeconfig file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

      Returned Value: root:root

      Result: Pass

      2.2.7 - Ensure that the certificate authorities file permissions are set to 644 or more restrictive (Scored)​

      Audit

      stat -c %a /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: 644

      Result: Pass

      2.2.8 - Ensure that the client certificate authorities file ownership is set to root:root (Scored)​

      Audit

      stat -c %U:%G /etc/kubernetes/ssl/kube-ca.pem

      Returned Value: root:root

      Result: Pass

      2.2.9 - Ensure that the kubelet configuration file ownership is set to root:root (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Not Applicable

      2.2.10 - Ensure that the kubelet configuration file permissions are set to 644 or more restrictive (Scored)​

      Notes

      RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

      Result: Not Applicable

      Copyright © 2022 SUSE Rancher. All Rights Reserved.
      - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-hardening-guide-with-cis-v1.4.1-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-hardening-guide-with-cis-v1.4.1-benchmark.html index 48e81e830e8..6423336d342 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-hardening-guide-with-cis-v1.4.1-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-hardening-guide-with-cis-v1.4.1-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide v2.3.3 | Rancher Manager - + @@ -15,7 +15,7 @@ from the below command:

    • Look for the following options in the command section of the output:

    --anonymous-auth=false
    --profiling=false
    --service-account-lookup=true
    --enable-admission-plugins=ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy
    --encryption-provider-config=/etc/kubernetes/ssl/encryption.yaml
    --admission-control-config-file=/etc/kubernetes/admission.yaml
    --audit-log-path=/var/log/kube-audit/audit-log.json
    --audit-log-maxage=30
    --audit-log-maxbackup=10
    --audit-log-maxsize=100
    --audit-log-format=json
    --audit-policy-file=/etc/kubernetes/audit-policy.yaml
    --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
    • In the volume section of the output ensure the bind mount is present:
    /var/log/kube-audit:/var/log/kube-audit

    Remediation

    • In the RKE cluster.yml add the following directives to the kube-api section under services:
    services:
      kube_api:
        always_pull_images: true
        pod_security_policy: true
        service_node_port_range: 30000-32767
        event_rate_limit:
          enabled: true
        audit_log:
          enabled: true
        secrets_encryption_config:
          enabled: true
        extra_args:
          anonymous-auth: "false"
          enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
          profiling: "false"
          service-account-lookup: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        extra_binds:
          - "/opt/kubernetes:/opt/kubernetes"

    For k8s 1.14 enable-admission-plugins should be

            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,PodSecurityPolicy,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,Priority,EventRateLimit"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    NOTE:

    Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

    2.1.3 - Configure scheduler options​

    Profile Applicability

    • Level 1

    Description

    Set the appropriate options for the Kubernetes scheduling service.

    NOTE: Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

    Rationale

    To address the following controls on the CIS benchmark, the command line options should be set on the Kubernetes scheduler.

    • 1.2.1 - Ensure that the --profiling argument is set to false (Scored)
    • 1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

    Audit

    • On nodes with the controlplane role: inspect the kube-scheduler containers:
    docker inspect kube-scheduler
    • Verify the following options are set in the command section.
    --profiling=false
    --address=127.0.0.1

    Remediation

    • In the RKE cluster.yml file ensure the following options are set:
    services:
      scheduler:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    2.1.4 - Configure controller options​

    Profile Applicability

    • Level 1

    Description

    Set the appropriate arguments on the Kubernetes controller manager.

    5*NOTE:** Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

    Rationale

    To address the following controls the options need to be passed to the Kubernetes controller manager.

    • 1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)
    • 1.3.2 - Ensure that the --profiling argument is set to false (Scored)
    • 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
    • 1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

    Audit

    • On nodes with the controlplane role inspect the kube-controller-manager container:
    docker inspect kube-controller-manager
    • Verify the following options are set in the command section:
    --terminated-pod-gc-threshold=1000
    --profiling=false
    --address=127.0.0.1
    --feature-gates="RotateKubeletServerCertificate=true"

    Remediation

    • In the RKE cluster.yml file ensure the following options are set:
    services:
      kube-controller:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
          terminated-pod-gc-threshold: "1000"
          feature-gates: "RotateKubeletServerCertificate=true"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    2.1.5 - Configure addons and PSPs​

    Profile Applicability

    • Level 1

    Description

    Configure a restrictive pod security policy (PSP) as the default and create role bindings for system level services to use the less restrictive default PSP.

    Rationale

    To address the following controls, a restrictive default PSP needs to be applied as the default. Role bindings need to be in place to allow system services to still function.

    • 1.7.1 - Do not admit privileged containers (Not Scored)
    • 1.7.2 - Do not admit containers wishing to share the host process ID namespace (Not Scored)
    • 1.7.3 - Do not admit containers wishing to share the host IPC namespace (Not Scored)
    • 1.7.4 - Do not admit containers wishing to share the host network namespace (Not Scored)
    • 1.7.5 - Do not admit containers with allowPrivilegeEscalation (Not Scored)
    • 1.7.6 - Do not admit root containers (Not Scored)
    • 1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)

    Audit

    • Verify that the cattle-system namespace exists:
    kubectl get ns |grep cattle
    • Verify that the roles exist:
    kubectl get role default-psp-role -n ingress-nginx
    kubectl get role default-psp-role -n cattle-system
    kubectl get clusterrole restricted-clusterrole
    • Verify the bindings are set correctly:
    kubectl get rolebinding -n ingress-nginx default-psp-rolebinding
    kubectl get rolebinding -n cattle-system default-psp-rolebinding
    kubectl get clusterrolebinding restricted-clusterrolebinding
    • Verify the restricted PSP is present.
    kubectl get psp restricted-psp

    Remediation

    • In the RKE cluster.yml file ensure the following options are set:
    addons: |
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: default-psp-role
        namespace: ingress-nginx
      rules:
      - apiGroups:
        - extensions
        resourceNames:
        - default-psp
        resources:
        - podsecuritypolicies
        verbs:
        - use
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: default-psp-rolebinding
        namespace: ingress-nginx
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: default-psp-role
      subjects:
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:serviceaccounts
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:authenticated
      ---
      apiVersion: v1
      kind: Namespace
      metadata:
        name: cattle-system
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: Role
      metadata:
        name: default-psp-role
        namespace: cattle-system
      rules:
      - apiGroups:
        - extensions
        resourceNames:
        - default-psp
        resources:
        - podsecuritypolicies
        verbs:
        - use
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: default-psp-rolebinding
        namespace: cattle-system
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: Role
        name: default-psp-role
      subjects:
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:serviceaccounts
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:authenticated
      ---
      apiVersion: policy/v1beta1
      kind: PodSecurityPolicy
      metadata:
        name: restricted-psp
      spec:
        requiredDropCapabilities:
        - NET_RAW
        privileged: false
        allowPrivilegeEscalation: false
        defaultAllowPrivilegeEscalation: false
        fsGroup:
          rule: RunAsAny
        runAsUser:
          rule: MustRunAsNonRoot
        seLinux:
          rule: RunAsAny
        supplementalGroups:
          rule: RunAsAny
        volumes:
        - emptyDir
        - secret
        - persistentVolumeClaim
        - downwardAPI
        - configMap
        - projected
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: restricted-clusterrole
      rules:
      - apiGroups:
        - extensions
        resourceNames:
        - restricted-psp
        resources:
        - podsecuritypolicies
        verbs:
        - use
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: restricted-clusterrolebinding
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: restricted-clusterrole
      subjects:
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:serviceaccounts
      - apiGroup: rbac.authorization.k8s.io
        kind: Group
        name: system:authenticated
    • Reconfigure the cluster:
    rke up --config cluster.yml

    3.1 - Rancher Management Control Plane Installation​

    3.1.1 - Disable the local cluster option​

    Profile Applicability

    • Level 2

    Description

    When deploying Rancher, disable the local cluster option on the Rancher Server.

    NOTE: This requires Rancher v2.1.2 or above.

    Rationale

    Having access to the local cluster from the Rancher UI is convenient for troubleshooting and debugging; however, if the local cluster is enabled in the Rancher UI, a user has access to all elements of the system, including the Rancher management server itself. Disabling the local cluster is a defense in depth measure and removes the possible attack vector from the Rancher UI and API.

    Audit

    • Verify the Rancher deployment has the --add-local=false option set.
    kubectl get deployment rancher -n cattle-system -o yaml |grep 'add-local'
    • In the Rancher UI go to Clusters in the Global view and verify that no local cluster is present.

    Remediation

    • While upgrading or installing Rancher 2.3.3 or above, provide the following flag:
    --set addLocal="false"

    3.1.2 - Enable Rancher Audit logging​

    Profile Applicability

    • Level 1

    Description

    Enable Rancher’s built-in audit logging capability.

    Rationale

    Tracking down what actions were performed by users in Rancher can provide insight during post mortems, and if monitored proactively can be used to quickly detect malicious actions.

    Audit

    • Verify that the audit log parameters were passed into the Rancher deployment.
    kubectl get deployment rancher -n cattle-system -o yaml | grep auditLog

    • Verify that the log is going to the appropriate destination, as set by auditLog.destination

      • sidecar:

        1. List pods:

          kubectl get pods -n cattle-system

        2. Tail logs:

          kubectl logs <pod> -n cattle-system -c rancher-audit-log

      • hostPath

        1. On the worker nodes running the Rancher pods, verify that the log files are being written to the destination indicated in auditlog.hostPath.

    Remediation

    Upgrade the Rancher server installation using Helm, and configure the audit log settings. The instructions for doing so can be found in the reference section below.

    Reference​

    3.2 - Rancher Management Control Plane Authentication​

    3.2.1 - Change the local admin password from the default value​

    Profile Applicability

    • Level 1

    Description

    The local admin password should be changed from the default.

    Rationale

    The default admin password is common across all Rancher installations and should be changed immediately upon startup.

    Audit

    Attempt to login into the UI with the following credentials:

    • Username: admin
    • Password: admin

    The login attempt must not succeed.

    Remediation

    Change the password from admin to a password that meets the recommended password standards for your organization.

    3.2.2 - Configure an Identity Provider for Authentication​

    Profile Applicability

    • Level 1

    Description

    When running Rancher in a production environment, configure an identity provider for authentication.

    Rationale

    Rancher supports several authentication backends that are common in enterprises. It is recommended to tie Rancher into an external authentication system to simplify user and group access in the Rancher cluster. Doing so assures that access control follows the organization's change management process for user accounts.

    Audit

    • In the Rancher UI, select Global
    • Select Security
    • Select Authentication
    • Ensure the authentication provider for your environment is active and configured correctly

    Remediation

    Configure the appropriate authentication provider for your Rancher installation according to the documentation found at the link in the reference section below.

    Reference​

    3.3 - Rancher Management Control Plane RBAC​

    3.3.1 - Ensure that administrator privileges are only granted to those who require them​

    Profile Applicability

    • Level 1

    Description

    Restrict administrator access to only those responsible for managing and operating the Rancher server.

    Rationale

    The admin privilege level gives the user the highest level of access to the Rancher server and all attached clusters. This privilege should only be granted to a few people who are responsible for the availability and support of Rancher and the clusters that it manages.

    Audit

    The following script uses the Rancher API to show users with administrator privileges:

    #!/bin/bash
    for i in $(curl -sk -u 'token-<id>:<secret>' https://<RANCHER_URL>/v3/users|jq -r .data[].links.globalRoleBindings); do

    curl -sk -u 'token-<id>:<secret>' $i| jq '.data[] | "\(.userId) \(.globalRoleId)"'

    done

    The admin role should only be assigned to users that require administrative privileges. Any role that is not admin or user should be audited in the RBAC section of the UI to ensure that the privileges adhere to policies for global access.

    The Rancher server permits customization of the default global permissions. We recommend that auditors also review the policies of any custom global roles.

    Remediation

    Remove the admin role from any user that does not require administrative privileges.

    3.4 - Rancher Management Control Plane Configuration​

    3.4.1 - Ensure only approved node drivers are active​

    Profile Applicability

    • Level 1

    Description

    Ensure that node drivers that are not needed or approved are not active in the Rancher console.

    Rationale

    Node drivers are used to provision compute nodes in various cloud providers and local IaaS infrastructure. For convenience, popular cloud providers are enabled by default. If the organization does not intend to use these or does not allow users to provision resources in certain providers, the drivers should be disabled. This will prevent users from using Rancher resources to provision the nodes.

    Audit

    • In the Rancher UI select Global
    • Select Node Drivers
    • Review the list of node drivers that are in an Active state.

    Remediation

    If a disallowed node driver is active, visit the Node Drivers page under Global and disable it.

    4.1 - Rancher Kubernetes Custom Cluster Configuration via RKE​

    (See Appendix C. for full RKE template example)

    4.1.1 - Configure kubelet options​

    Profile Applicability

    • Level 1

    Description

    Ensure Kubelet options are configured to match CIS controls.

    Rationale

    To pass the following controls in the CIS benchmark, ensure the appropriate flags are passed to the Kubelet.

    • 2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
    • 2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)
    • 2.1.6 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)
    • 2.1.7 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)
    • 2.1.8 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)
    • 2.1.10 - Ensure that the --event-qps argument is set to 0 (Scored)
    • 2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
    • 2.1.14 - Ensure that the Kubelet only makes use of Strong Cryptographic Ciphers (Not Scored)

    Audit

    Inspect the Kubelet containers on all hosts and verify that they are running with the following options:

    • --streaming-connection-idle-timeout=<duration greater than 0>
    • --authorization-mode=Webhook
    • --protect-kernel-defaults=true
    • --make-iptables-util-chains=true
    • --event-qps=0
    • --anonymous-auth=false
    • --feature-gates="RotateKubeletServerCertificate=true"
    • --tls-cipher-suites="TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

    Remediation

    • Add the following to the RKE cluster.yml kubelet section under services:
    services:
      kubelet:
        generate_serving_certificate: true
        extra_args:
          feature-gates: "RotateKubeletServerCertificate=true"
          protect-kernel-defaults: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"

    Where <duration> is in a form like 1800s.

    • Reconfigure the cluster:
    rke up --config cluster.yml

    4.1.2 - Configure kube-api options​

    Profile Applicability

    • Level 1

    Description

    Ensure the RKE configuration is set to deploy the kube-api service with the options required for controls.

    NOTE:

    Enabling the AlwaysPullImages admission control plugin can cause degraded performance due to overhead of always pulling images. Enabling the DenyEscalatingExec admission control plugin will prevent the 'Launch kubectl' functionality in the UI from working.

    Rationale

    To pass the following controls for the kube-api server ensure RKE configuration passes the appropriate options.

    • 1.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)
    • 1.1.8 - Ensure that the --profiling argument is set to false (Scored)
    • 1.1.11 - Ensure that the admission control plugin AlwaysPullImages is set (Scored)
    • 1.1.12 - Ensure that the admission control plugin DenyEscalatingExec is set (Scored)
    • 1.1.14 - Ensure that the admission control plugin NamespaceLifecycle is set (Scored)
    • 1.1.15 - Ensure that the --audit-log-path argument is set as appropriate (Scored)
    • 1.1.16 - Ensure that the --audit-log-maxage argument is set as appropriate (Scored)
    • 1.1.17 - Ensure that the --audit-log-maxbackup argument is set as appropriate (Scored)
    • 1.1.18 - Ensure that the --audit-log-maxsize argument is set as appropriate (Scored)
    • 1.1.23 - Ensure that the --service-account-lookup argument is set to true (Scored)
    • 1.1.24 - Ensure that the admission control plugin PodSecurityPolicy is set (Scored)
    • 1.1.30 Ensure that the API Server only makes use of Strong Cryptographic Ciphers (Not Scored)
    • 1.1.34 - Ensure that the --encryption-provider-config argument is set as appropriate (Scored)
    • 1.1.35 - Ensure that the encryption provider is set to aescbc (Scored)
    • 1.1.36 - Ensure that the admission control plugin EventRateLimit is set (Scored)
    • 1.1.37 - Ensure that the AdvancedAuditing argument is not set to false (Scored)

    Audit

    • On nodes with the controlplane role inspect the kube-apiserver containers:

      docker inspect kube-apiserver

    • Look for the following options in the command section of the output:

    --anonymous-auth=false
    --profiling=false
    --service-account-lookup=true
    --enable-admission-plugins=ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy
    --encryption-provider-config=/etc/kubernetes/ssl/encryption.yaml
    --admission-control-config-file=/etc/kubernetes/admission.yaml
    --audit-log-path=/var/log/kube-audit/audit-log.json
    --audit-log-maxage=30
    --audit-log-maxbackup=10
    --audit-log-maxsize=100
    --audit-log-format=json
    --audit-policy-file=/etc/kubernetes/audit-policy.yaml
    --tls-cipher-suites=TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
    • In the volume section of the output ensure the bind mount is present:
    /var/log/kube-audit:/var/log/kube-audit

    Remediation

    • In the RKE cluster.yml add the following directives to the kube-api section under services:
    services:
      kube_api:
        always_pull_images: true
        pod_security_policy: true
        service_node_port_range: 30000-32767
        event_rate_limit:
          enabled: true
        audit_log:
          enabled: true
        secrets_encryption_config:
          enabled: true
        extra_args:
          anonymous-auth: "false"
          enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
          profiling: "false"
          service-account-lookup: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        extra_binds:
          - "/opt/kubernetes:/opt/kubernetes"

    For k8s 1.14 enable-admission-plugins should be

            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,PodSecurityPolicy,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,Priority,EventRateLimit"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    NOTE:

    Files that are placed in /opt/kubernetes need to be mounted in using the extra_binds functionality in RKE.

    4.1.3 - Configure scheduler options​

    Profile Applicability

    • Level 1

    Description

    Set the appropriate options for the Kubernetes scheduling service.

    NOTE: Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

    Rationale

    To address the following controls on the CIS benchmark, the command line options should be set on the Kubernetes scheduler.

    • 1.2.1 - Ensure that the --profiling argument is set to false (Scored)
    • 1.2.2 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

    Audit

    • On nodes with the controlplane role: inspect the kube-scheduler containers:
    docker inspect kube-scheduler
    • Verify the following options are set in the command section.
    --profiling=false
    --address=127.0.0.1

    Remediation

    • In the RKE cluster.yml file ensure the following options are set:
    services:
      scheduler:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    4.1.4 - Configure controller options​

    Profile Applicability

    • Level 1

    Description

    Set the appropriate arguments on the Kubernetes controller manager.

    5*NOTE:** Setting --address to 127.0.0.1 will prevent Rancher cluster monitoring from scraping this endpoint.

    Rationale

    To address the following controls the options need to be passed to the Kubernetes controller manager.

    • 1.3.1 - Ensure that the --terminated-pod-gc-threshold argument is set as appropriate (Scored)
    • 1.3.2 - Ensure that the --profiling argument is set to false (Scored)
    • 1.3.6 Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)
    • 1.3.7 - Ensure that the --address argument is set to 127.0.0.1 (Scored)

    Audit

    • On nodes with the controlplane role inspect the kube-controller-manager container:
    docker inspect kube-controller-manager
    • Verify the following options are set in the command section:
    --terminated-pod-gc-threshold=1000
    --profiling=false
    --address=127.0.0.1
    --feature-gates="RotateKubeletServerCertificate=true"

    Remediation

    • In the RKE cluster.yml file ensure the following options are set:
    services:
      kube-controller:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
          terminated-pod-gc-threshold: "1000"
          feature-gates: "RotateKubeletServerCertificate=true"
    • Reconfigure the cluster:
    rke up --config cluster.yml

    4.1.5 - Check PSPs​

    Profile Applicability

    • Level 1

    Description

    Configure a restrictive pod security policy (PSP) as the default and create role bindings for system level services to use the less restrictive default PSP.

    Rationale

    To address the following controls, a restrictive default PSP needs to be applied as the default. Role bindings need to be in place to allow system services to still function.

    • 1.7.1 - Do not admit privileged containers (Not Scored)
    • 1.7.2 - Do not admit containers wishing to share the host process ID namespace (Not Scored)
    • 1.7.3 - Do not admit containers wishing to share the host IPC namespace (Not Scored)
    • 1.7.4 - Do not admit containers wishing to share the host network namespace (Not Scored)
    • 1.7.5 - Do not admit containers with allowPrivilegeEscalation (Not Scored)
    • 1.7.6 - Do not admit root containers (Not Scored)
    • 1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)

    Audit

    • Verify that the cattle-system namespace exists:
    kubectl get ns |grep cattle
    • Verify that the roles exist:
    kubectl get role default-psp-role -n ingress-nginx
    kubectl get role default-psp-role -n cattle-system
    kubectl get clusterrole restricted-clusterrole
    • Verify the bindings are set correctly:
    kubectl get rolebinding -n ingress-nginx default-psp-rolebinding
    kubectl get rolebinding -n cattle-system default-psp-rolebinding
    • Verify the restricted PSP is present.
    kubectl get psp restricted-psp

    Appendix A - Complete ubuntu cloud-config Example​

    cloud-config file to automate hardening manual steps on nodes deployment.

    #cloud-config
    bootcmd:
    - apt-get update
    - apt-get install -y apt-transport-https
    apt:
      sources:
        docker:
          source: "deb [arch=amd64] https://download.docker.com/linux/ubuntu $RELEASE stable"
          keyid: 0EBFCD88
    packages:
    - [docker-ce, '5:19.03.5~3-0~ubuntu-bionic']
    - jq
    write_files:
    # 1.1.1 - Configure default sysctl settings on all hosts
    - path: /etc/sysctl.d/90-kubelet.conf
      owner: root:root
      permissions: '0644'
      content: |
        vm.overcommit_memory=1
        vm.panic_on_oom=0
        kernel.panic=10
        kernel.panic_on_oops=1
        kernel.keys.root_maxkeys=1000000
        kernel.keys.root_maxbytes=25000000
    # 1.4.12 etcd user
    groups:
      - etcd
    users:
      - default
      - name: etcd
        gecos: Etcd user
        primary_group: etcd
        homedir: /var/lib/etcd
    # 1.4.11 etcd data dir
    runcmd:
      - chmod 0700 /var/lib/etcd
      - usermod -G docker -a ubuntu
      - sysctl -p /etc/sysctl.d/90-kubelet.conf

    Appendix B - Complete RKE cluster.yml Example​

    Before apply, replace rancher_kubernetes_engine_config.services.etcd.gid and rancher_kubernetes_engine_config.services.etcd.uid with the proper etcd group and user ids that were created on etcd nodes.

    RKE yaml for k8s 1.14
    nodes:
    - address: 18.191.190.205
      internal_address: 172.31.24.213
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.203
      internal_address: 172.31.24.203
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.10
      internal_address: 172.31.24.244
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    addon_job_timeout: 30
    authentication:
      strategy: x509
    authorization: {}
    bastion_host:
      ssh_agent_auth: false
    cloud_provider: {}
    ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
    ingress:
      provider: nginx
    kubernetes_version: v1.14.9-rancher1-1
    monitoring:
      provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
    network:
      options:
        flannel_backend_type: vxlan
      plugin: canal
    restore:
      restore: false
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
    services:
      etcd:
        backup_config:
          enabled: true
          interval_hours: 12
          retention: 6
          safe_timestamp: false
        creation: 12h
        extra_args:
          election-timeout: '5000'
          heartbeat-interval: '500'
        gid: 1000
        retention: 72h
        snapshot: false
        uid: 1000
      kube-api:
        always_pull_images: true
        audit_log:
          enabled: true
        event_rate_limit:
          enabled: true
        extra_args:
          anonymous-auth: 'false'
          enable-admission-plugins: >-
            ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,PodSecurityPolicy,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,Priority,EventRateLimit
          profiling: 'false'
          service-account-lookup: 'true'
          tls-cipher-suites: >-
            TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
        extra_binds:
          - '/opt/kubernetes:/opt/kubernetes'
        pod_security_policy: true
        secrets_encryption_config:
          enabled: true
        service_node_port_range: 30000-32767
      kube-controller:
        extra_args:
          address: 127.0.0.1
          feature-gates: RotateKubeletServerCertificate=true
          profiling: 'false'
          terminated-pod-gc-threshold: '1000'
      kubelet:
        extra_args:
          protect-kernel-defaults: 'true'
        fail_swap_on: false
        generate_serving_certificate: true
      kubeproxy: {}
      scheduler:
        extra_args:
          address: 127.0.0.1
          profiling: 'false'
    ssh_agent_auth: false
    RKE yaml for k8s 1.15
    nodes:
    - address: 18.191.190.205
      internal_address: 172.31.24.213
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.203
      internal_address: 172.31.24.203
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.10
      internal_address: 172.31.24.244
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    addon_job_timeout: 30
    authentication:
      strategy: x509
    ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
    ingress:
      provider: nginx
    kubernetes_version: v1.15.6-rancher1-2
    monitoring:
      provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
    network:
      options:
        flannel_backend_type: vxlan
      plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
    services:
      etcd:
        backup_config:
          enabled: true
          interval_hours: 12
          retention: 6
          safe_timestamp: false
        creation: 12h
        extra_args:
          election-timeout: 5000
          heartbeat-interval: 500
        gid: 1000
        retention: 72h
        snapshot: false
        uid: 1000
      kube_api:
        always_pull_images: true
        pod_security_policy: true
        service_node_port_range: 30000-32767
        event_rate_limit:
          enabled: true
        audit_log:
          enabled: true
        secrets_encryption_config:
          enabled: true
        extra_args:
          anonymous-auth: "false"
          enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
          profiling: "false"
          service-account-lookup: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        extra_binds:
          - "/opt/kubernetes:/opt/kubernetes"
      kubelet:
        generate_serving_certificate: true
        extra_args:
          feature-gates: "RotateKubeletServerCertificate=true"
          protect-kernel-defaults: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
      kube-controller:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
          terminated-pod-gc-threshold: "1000"
          feature-gates: "RotateKubeletServerCertificate=true"
      scheduler:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
    ssh_agent_auth: false
    RKE yaml for k8s 1.16
    nodes:
    - address: 18.191.190.205
      internal_address: 172.31.24.213
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.203
      internal_address: 172.31.24.203
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    - address: 18.191.190.10
      internal_address: 172.31.24.244
      user: ubuntu
      role: [ "controlplane", "etcd", "worker" ]
    addon_job_timeout: 30
    authentication:
      strategy: x509
    ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
    ingress:
      provider: nginx
    kubernetes_version: v1.16.3-rancher1-1
    monitoring:
      provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
    network:
      options:
        flannel_backend_type: vxlan
      plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
    services:
      etcd:
        backup_config:
          enabled: true
          interval_hours: 12
          retention: 6
          safe_timestamp: false
        creation: 12h
        extra_args:
          election-timeout: 5000
          heartbeat-interval: 500
        gid: 1000
        retention: 72h
        snapshot: false
        uid: 1000
      kube_api:
        always_pull_images: true
        pod_security_policy: true
        service_node_port_range: 30000-32767
        event_rate_limit:
          enabled: true
        audit_log:
          enabled: true
        secrets_encryption_config:
          enabled: true
        extra_args:
          anonymous-auth: "false"
          enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
          profiling: "false"
          service-account-lookup: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        extra_binds:
          - "/opt/kubernetes:/opt/kubernetes"
      kubelet:
        generate_serving_certificate: true
        extra_args:
          feature-gates: "RotateKubeletServerCertificate=true"
          protect-kernel-defaults: "true"
          tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
      kube-controller:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
          terminated-pod-gc-threshold: "1000"
          feature-gates: "RotateKubeletServerCertificate=true"
      scheduler:
        extra_args:
          profiling: "false"
          address: "127.0.0.1"
    ssh_agent_auth: false

    Appendix C - Complete RKE Template Example​

    Before apply, replace rancher_kubernetes_engine_config.services.etcd.gid and rancher_kubernetes_engine_config.services.etcd.uid with the proper etcd group and user ids that were created on etcd nodes.

    RKE template for k8s 1.14
    #
    # Cluster Config
    #
    answers: {}
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: false
    name: test-35378
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      authentication:
        strategy: x509
      authorization: {}
      bastion_host:
        ssh_agent_auth: false
      cloud_provider: {}
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.14.9-rancher1-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
      restore:
        restore: false
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: '5000'
            heartbeat-interval: '500'
          gid: 1000
          retention: 72h
          snapshot: false
          uid: 1000
        kube-api:
          always_pull_images: true
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          extra_args:
            anonymous-auth: 'false'
            enable-admission-plugins: >-
              ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,PodSecurityPolicy,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,Priority,EventRateLimit
            profiling: 'false'
            service-account-lookup: 'true'
            tls-cipher-suites: >-
              TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          extra_binds:
            - '/opt/kubernetes:/opt/kubernetes'
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube-controller:
          extra_args:
            address: 127.0.0.1
            feature-gates: RotateKubeletServerCertificate=true
            profiling: 'false'
            terminated-pod-gc-threshold: '1000'
        kubelet:
          extra_args:
            protect-kernel-defaults: 'true'
          fail_swap_on: false
          generate_serving_certificate: true
        kubeproxy: {}
        scheduler:
          extra_args:
            address: 127.0.0.1
            profiling: 'false'
      ssh_agent_auth: false
    windows_prefered_cluster: false
    RKE template for k8s 1.15
    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.6-rancher1-2
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 1000
          retention: 72h
          snapshot: false
          uid: 1000
        kube_api:
          always_pull_images: true
          pod_security_policy: true
          service_node_port_range: 30000-32767
          event_rate_limit:
            enabled: true
          audit_log:
            enabled: true
          secrets_encryption_config:
            enabled: true
          extra_args:
            anonymous-auth: "false"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            profiling: "false"
            service-account-lookup: "true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/opt/kubernetes:/opt/kubernetes"
        kubelet:
          generate_serving_certificate: true
          extra_args:
            feature-gates: "RotateKubeletServerCertificate=true"
            protect-kernel-defaults: "true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
        scheduler:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
      ssh_agent_auth: false
    windows_prefered_cluster: false
    RKE template for k8s 1.16
    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.16.3-rancher1-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 1000
          retention: 72h
          snapshot: false
          uid: 1000
        kube_api:
          always_pull_images: true
          pod_security_policy: true
          service_node_port_range: 30000-32767
          event_rate_limit:
            enabled: true
          audit_log:
            enabled: true
          secrets_encryption_config:
            enabled: true
          extra_args:
            anonymous-auth: "false"
            enable-admission-plugins: "ServiceAccount,NamespaceLifecycle,LimitRanger,PersistentVolumeLabel,DefaultStorageClass,ResourceQuota,DefaultTolerationSeconds,AlwaysPullImages,DenyEscalatingExec,NodeRestriction,EventRateLimit,PodSecurityPolicy"
            profiling: "false"
            service-account-lookup: "true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
          extra_binds:
            - "/opt/kubernetes:/opt/kubernetes"
        kubelet:
          generate_serving_certificate: true
          extra_args:
            feature-gates: "RotateKubeletServerCertificate=true"
            protect-kernel-defaults: "true"
            tls-cipher-suites: "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256"
        kube-controller:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
            terminated-pod-gc-threshold: "1000"
            feature-gates: "RotateKubeletServerCertificate=true"
        scheduler:
          extra_args:
            profiling: "false"
            address: "127.0.0.1"
      ssh_agent_auth: false
    windows_prefered_cluster: false
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-self-assessment-guide-with-cis-v1.4.1-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-self-assessment-guide-with-cis-v1.4.1-benchmark.html index ecf5866de67..08015f946ec 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-self-assessment-guide-with-cis-v1.4.1-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.3-self-assessment-guide-with-cis-v1.4.1-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide - Rancher v2.3.3 | Rancher Manager - + @@ -18,7 +18,7 @@ Key file name may vary slightly, since it contains the IP of the etcd container. Certificate file name may vary slightly, since it contains the IP of the etcd container.

    Returned Value: --peer-cert-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135.pem

    Audit (--peer-key-file)

    docker inspect etcd | jq -e '.[0].Args[] | match("--peer-key-file=.*").string'

    Note Key file name may vary slightly, since it contains the IP of the etcd container.

    Returned Value: --peer-key-file=/etc/kubernetes/ssl/kube-etcd-172-31-22-135-key.pem

    Result: Pass

    1.5.5 - Ensure that the --peer-client-cert-auth argument is set to true (Scored)​

    Notes

    Setting --peer-client-cert-auth is the equivalent of setting --peer-client-cert-auth=true.

    Audit

    docker inspect etcd | jq -e '.[0].Args[] | match("--peer-client-cert-auth(=true)*").string'

    Returned Value: --peer-client-cert-auth

    Result: Pass

    1.5.6 - Ensure that the --peer-auto-tls argument is not set to true (Scored)​

    Audit

    docker inspect etcd | jq -e '.[0].Args[] | match("--peer-auto-tls(?:(?!=false).*)").string'

    Returned Value: null

    Result: Pass

    1.5.7 - Ensure that a unique Certificate Authority is used for etcd (Not Scored)​

    Mitigation

    RKE supports connecting to an external etcd cluster. This external cluster could be configured with its own discreet CA.

    Notes

    --trusted-ca-file is set and different from the --client-ca-file used by kube-apiserver.

    Audit

    docker inspect etcd | jq -e '.[0].Args[] | match("--trusted-ca-file=(?:(?!/etc/kubernetes/ssl/kube-ca.pem).*)").string'

    Returned Value: null

    Result: Pass (See Mitigation)

    1.6 - General Security Primitives​

    These "Not Scored" controls are implementation best practices. To ease the administrative burden, we recommend that you implement these best practices on your workload clusters by creating clusters with Rancher rather than using RKE alone.

    1.6.1 - Ensure that the cluster-admin role is only used where required (Not Scored)​

    Rancher has built in support for maintaining and enforcing Kubernetes RBAC on your workload clusters.

    Rancher has the ability integrate with external authentication sources (LDAP, SAML, AD…) allows easy access with unique credentials to your existing users or groups.

    1.6.2 - Create administrative boundaries between resources using namespaces (Not Scored)​

    With Rancher, users or groups can be assigned access to all clusters, a single cluster or a "Project" (a group of one or more namespaces in a cluster). This allows granular access control to cluster resources.

    1.6.3 - Create network segmentation using Network Policies (Not Scored)​

    Rancher can (optionally) automatically create Network Policies to isolate "Projects" (a group of one or more namespaces) in a cluster.

    See "Cluster Options" when creating a cluster with Rancher to turn on Network Isolation.

    1.6.4 - Ensure that the seccomp profile is set to docker/default in your pod definitions (Not Scored)​

    Since this requires the enabling of AllAlpha feature gates we would not recommend enabling this feature at the moment.

    1.6.5 - Apply security context to your pods and containers (Not Scored)​

    This practice does go against control 1.1.13, but we prefer using a PodSecurityPolicy and allowing security context to be set over a blanket deny.

    Rancher allows users to set various Security Context options when launching pods via the GUI interface.

    1.6.6 - Configure image provenance using the ImagePolicyWebhook admission controller (Not Scored)​

    Image Policy Webhook requires a 3rd party service to enforce policy. This can be configured in the --admission-control-config-file. See the Host configuration section for the admission.yaml file.

    1.6.7 - Configure network policies as appropriate (Not Scored)​

    Rancher can (optionally) automatically create Network Policies to isolate projects (a group of one or more namespaces) within a cluster.

    See the Cluster Options section when creating a cluster with Rancher to turn on network isolation.

    1.6.8 - Place compensating controls in the form of PodSecurityPolicy (PSP) and RBAC for privileged container usage (Not Scored)​

    Section 1.7 of this guide shows how to add and configure a default "restricted" PSP based on controls.

    With Rancher you can create a centrally maintained "restricted" PSP and deploy it to all of the clusters that Rancher manages.

    1.7 - Pod Security Policies (PSP)​

    This RKE configuration has two Pod Security Policies.

    • default-psp: assigned to namespaces that require additional privileged access: kube-system, ingress-nginx and cattle-system.
    • restricted-psp: This is the cluster default PSP and follows the best practices defined by controls in this section.

    1.7.1 - Do not admit privileged containers (Not Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.privileged}' | grep "true"

    Returned Value: null

    Result: Pass

    1.7.2 - Do not admit containers wishing to share the host process ID namespace (Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.hostPID}' | grep "true"

    Returned Value: null

    Result: Pass

    1.7.3 - Do not admit containers wishing to share the host IPC namespace (Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.hostIPC}' | grep "true"

    Returned Value: null

    Result: Pass

    1.7.4 - Do not admit containers wishing to share the host network namespace (Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.hostNetwork}' | grep "true"

    Returned Value: null

    Result: Pass

    1.7.5 - Do not admit containers with allowPrivilegeEscalation (Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.allowPrivilegeEscalation}' | grep "true"

    Returned Value: null

    Result: Pass

    1.7.6 - Do not admit containers whose processes run as root (Not Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.runAsUser.rule}' | grep "RunAsAny"

    Returned Value: RunAsAny

    Result: Pass

    1.7.7 - Do not admit containers with dangerous capabilities (Not Scored)​

    Notes

    The restricted PodSecurityPolicy is available to all ServiceAccounts.

    Audit

    kubectl get psp restricted-psp -o jsonpath='{.spec.requiredDropCapabilities}' | grep "NET_RAW"

    Returned Value: null

    Result: Pass

    2 - Worker Node Security Configuration​

    2.1 - Kubelet​

    2.1.1 - Ensure that the --anonymous-auth argument is set to false (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--anonymous-auth=false").string'

    Returned Value: --anonymous-auth=false

    Result: Pass

    2.1.2 - Ensure that the --authorization-mode argument is not set to AlwaysAllow (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--authorization-mode=Webhook").string'

    Returned Value: --authorization-mode=Webhook

    Result: Pass

    2.1.3 - Ensure that the --client-ca-file argument is set as appropriate (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--client-ca-file=.*").string'

    Returned Value: --client-ca-file=/etc/kubernetes/ssl/kube-ca.pem

    Result: Pass

    2.1.4 - Ensure that the --read-only-port argument is set to 0 (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--read-only-port=0").string'

    Returned Value: --read-only-port=0

    Result: Pass

    2.1.5 - Ensure that the --streaming-connection-idle-timeout argument is not set to 0 (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--streaming-connection-idle-timeout=.*").string'

    Returned Value: --streaming-connection-idle-timeout=30m

    Result: Pass

    2.1.6 - Ensure that the --protect-kernel-defaults argument is set to true (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--protect-kernel-defaults=true").string'

    Returned Value: --protect-kernel-defaults=true

    Result: Pass

    2.1.7 - Ensure that the --make-iptables-util-chains argument is set to true (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--make-iptables-util-chains=true").string'

    Returned Value: --make-iptables-util-chains=true

    Result: Pass

    2.1.8 - Ensure that the --hostname-override argument is not set (Scored)​

    Notes This is used by most cloud providers. Not setting this is not practical in most cases.

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--hostname-override=.*").string'

    Returned Value: --hostname-override=<ipv4 address>

    Result: Fail

    2.1.9 - Ensure that the --event-qps argument is set to 0 (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--event-qps=0").string'

    Returned Value: --event-qps=0

    Result: Pass

    2.1.10 - Ensure that the --tls-cert-file and --tls-private-key-file arguments are set as appropriate (Scored)​

    Notes

    RKE does not set these options and uses the kubelet's self generated certificates for TLS communication. These files are located in the default directory (/var/lib/kubelet/pki).

    Audit (--tls-cert-file)

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cert-file=.*").string'

    Returned Value: --tls-cert-file=/etc/kubernetes/ssl/kube-kubelet-172-31-40-84.pem

    Audit (--tls-private-key-file)

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-private-key-file=.*").string'

    Returned Value: --tls-private-key-file=/etc/kubernetes/ssl/kube-kubelet-172-31-40-84-key.pem

    Result: Pass

    2.1.11 - Ensure that the --cadvisor-port argument is set to 0 (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--cadvisor-port=0").string'

    Returned Value: null

    Result: Pass

    2.1.12 - Ensure that the --rotate-certificates argument is not set to false (Scored)​

    Notes

    RKE handles certificate rotation through an external process.

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--rotate-certificates=true").string'

    Returned Value: null

    Result: Pass (Not Applicable)

    2.1.13 - Ensure that the RotateKubeletServerCertificate argument is set to true (Scored)​

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--feature-gates=.*(RotateKubeletServerCertificate=true).*").captures[].string'

    Returned Value: RotateKubeletServerCertificate=true

    Result: Pass

    2.1.14 - Ensure that the kubelet only makes use of strong cryptographic ciphers (Not Scored)​

    Audit (Allowed Ciphers)

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

    Returned Value: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

    Returned Value: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305).*").captures[].string'

    Returned Value: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

    Returned Value: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305).*").captures[].string'

    Returned Value: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

    Returned Value: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_256_GCM_SHA384).*").captures[].string'

    Returned Value: TLS_RSA_WITH_AES_256_GCM_SHA384

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(TLS_RSA_WITH_AES_128_GCM_SHA256).*").captures[].string'

    Returned Value: TLS_RSA_WITH_AES_128_GCM_SHA256

    Audit (Disallowed Ciphers)

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(CBC).*").captures[].string'

    Returned Value: null

    Audit

    docker inspect kubelet | jq -e '.[0].Args[] | match("--tls-cipher-suites=.*(RC4).*").captures[].string'

    Returned Value: null

    Result: Pass

    2.2 - Configuration Files​

    2.2.1 - Ensure that the permissions for kubelet.conf are set to 644 or more restrictive (Scored)​

    Notes

    This is the value of the --kubeconfig option.

    Audit

    stat -c %a /etc/kubernetes/ssl/kubecfg-kube-node.yaml

    Returned Value: 640

    Result: Pass

    2.2.2 - Ensure that the kubelet.conf file ownership is set to root:root (Scored)​

    Notes

    This is the value of the --kubeconfig option.

    Audit

    stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-node.yaml

    Returned Value: root:root

    Result: Pass

    2.2.3 - Ensure that the kubelet service file permissions are set to 644 or more restrictive (Scored)​

    Notes

    RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

    Result: Pass (Not Applicable)

    2.2.4 - Ensure that the kubelet service file ownership is set to root:root (Scored)​

    Notes

    RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

    Result: Pass (Not Applicable)

    2.2.5 - Ensure that the proxy kubeconfig file permissions are set to 644 or more restrictive (Scored)​

    Audit

    stat -c %a /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

    Returned Value: 640

    Result: Pass

    2.2.6 - Ensure that the proxy kubeconfig file ownership is set to root:root (Scored)​

    Audit

    stat -c %U:%G /etc/kubernetes/ssl/kubecfg-kube-proxy.yaml

    Returned Value: root:root

    Result: Pass

    2.2.7 - Ensure that the certificate authorities file permissions are set to 644 or more restrictive (Scored)​

    Audit

    stat -c %a /etc/kubernetes/ssl/kube-ca.pem

    Returned Value: 640

    Result: Pass

    2.2.8 - Ensure that the client certificate authorities file ownership is set to root:root (Scored)​

    Audit

    stat -c %U:%G /etc/kubernetes/ssl/kube-ca.pem

    Returned Value: root:root

    Result: Pass

    2.2.9 - Ensure that the kubelet configuration file ownership is set to root:root (Scored)​

    Notes

    RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

    Result: Pass (Not Applicable)

    2.2.10 - Ensure that the kubelet configuration file permissions are set to 644 or more restrictive (Scored)​

    Notes

    RKE doesn't require or maintain a configuration file for kubelet. All configuration is passed in as arguments at container run time.

    Result: Pass (Not Applicable)

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-hardening-guide-with-cis-v1.5-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-hardening-guide-with-cis-v1.5-benchmark.html index e8fc3605271..656f055c544 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-hardening-guide-with-cis-v1.5-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-hardening-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide v2.3.5 | Rancher Manager - + @@ -33,7 +33,7 @@ RKE Templates are used to provision Kubernetes and define Rancher settings. Foll documentaion for additional installation and RKE Template details.

    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      addons: |-
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ingress-nginx
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: policy/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: tiller
          namespace: kube-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: tiller
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cluster-admin
        subjects:
        - kind: ServiceAccount
          name: tiller
          namespace: kube-system
      ignore_docker_version: true
      kubernetes_version: v1.15.9-rancher1-1
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        mtu: 0
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: false
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: '5000'
            heartbeat-interval: '500'
          gid: 52034
          retention: 72h
          snapshot: false
          uid: 52034
        kube_api:
          always_pull_images: false
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube_controller:
          extra_args:
            address: 127.0.0.1
            feature-gates: RotateKubeletServerCertificate=true
            profiling: 'false'
            terminated-pod-gc-threshold: '1000'
        kubelet:
          extra_args:
            anonymous-auth: 'false'
            event-qps: '0'
            feature-gates: RotateKubeletServerCertificate=true
            make-iptables-util-chains: 'true'
            protect-kernel-defaults: 'true'
            streaming-connection-idle-timeout: 1800s
            tls-cipher-suites: >-
              TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          fail_swap_on: false
          generate_serving_certificate: true
        scheduler:
          extra_args:
            address: 127.0.0.1
            profiling: 'false'
      ssh_agent_auth: false
    windows_prefered_cluster: false

    Hardened Reference Ubuntu 18.04 LTS cloud-config:​

    The reference cloud-config is generally used in cloud infrastructure environments to allow for configuration management of compute instances. The reference config configures Ubuntu operating system level settings needed before installing kubernetes.

    #cloud-config
    packages:
      - curl
      - jq
    runcmd:
      - sysctl -w vm.overcommit_memory=1
      - sysctl -w kernel.panic=10
      - sysctl -w kernel.panic_on_oops=1
      - curl https://releases.rancher.com/install-docker/18.09.sh | sh
      - usermod -aG docker ubuntu
      - return=1; while [ $return != 0 ]; do sleep 2; docker ps; return=$?; done
      - addgroup --gid 52034 etcd
      - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd
    write_files:
      - path: /etc/sysctl.d/kubelet.conf
        owner: root:root
        permissions: "0644"
        content: |
          vm.overcommit_memory=1
          kernel.panic=10
          kernel.panic_on_oops=1
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-self-assessment-guide-with-cis-v1.5-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-self-assessment-guide-with-cis-v1.5-benchmark.html index 56e84ebdf48..961c2d514e6 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-self-assessment-guide-with-cis-v1.5-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.3-hardening-guides/rancher-v2.3.5-self-assessment-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide - v2.3.5 | Rancher Manager - + @@ -234,7 +234,7 @@ Create a PSP as described in the Kubernetes documentation, ensuring that the Follow the documentation and create NetworkPolicy objects as you need them.

    Audit Script: 5.3.2.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-"/root/.kube/config"}

    kubectl version > /dev/null
    if [ $? -ne 0 ]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    for namespace in $(kubectl get namespaces -A -o json | jq -r '.items[].metadata.name'); do
      policy_count=$(kubectl get networkpolicy -n ${namespace} -o json | jq '.items | length')
      if [ ${policy_count} -eq 0 ]; then
        echo "fail: ${namespace}"
        exit 1
      fi
    done

    echo "pass"

    Audit Execution:

    ./5.3.2.sh

    Expected result:

    'pass' is present

    5.6 General Policies​

    5.6.4 The default namespace should not be used (Scored)​

    Result: PASS

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Audit Script: 5.6.4.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-/root/.kube/config}

    kubectl version > /dev/null
    if [[ $? -gt 0 ]]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    default_resources=$(kubectl get all -o json | jq --compact-output '.items[] | select((.kind == "Service") and (.metadata.name == "kubernetes") and (.metadata.namespace == "default") | not)' | wc -l)

    echo "--count=${default_resources}"

    Audit Execution:

    ./5.6.4.sh

    Expected result:

    '0' is equal to '0'
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html index 669b9c216e2..0cb1b61e364 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide v2.4 | Rancher Manager - + @@ -33,7 +33,7 @@ RKE Templates are used to provision Kubernetes and define Rancher settings. Foll documentaion for additional installation and RKE Template details.

    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      addons: |-
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ingress-nginx
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: policy/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: tiller
          namespace: kube-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: tiller
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cluster-admin
        subjects:
        - kind: ServiceAccount
          name: tiller
          namespace: kube-system
      ignore_docker_version: true
      kubernetes_version: v1.15.9-rancher1-1
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        mtu: 0
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: false
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: '5000'
            heartbeat-interval: '500'
          gid: 52034
          retention: 72h
          snapshot: false
          uid: 52034
        kube_api:
          always_pull_images: false
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube_controller:
          extra_args:
            address: 127.0.0.1
            feature-gates: RotateKubeletServerCertificate=true
            profiling: 'false'
            terminated-pod-gc-threshold: '1000'
        kubelet:
          extra_args:
            anonymous-auth: 'false'
            event-qps: '0'
            feature-gates: RotateKubeletServerCertificate=true
            make-iptables-util-chains: 'true'
            protect-kernel-defaults: 'true'
            streaming-connection-idle-timeout: 1800s
            tls-cipher-suites: >-
              TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          fail_swap_on: false
          generate_serving_certificate: true
        scheduler:
          extra_args:
            address: 127.0.0.1
            profiling: 'false'
      ssh_agent_auth: false
    windows_prefered_cluster: false

    Hardened Reference Ubuntu 18.04 LTS cloud-config:​

    The reference cloud-config is generally used in cloud infrastructure environments to allow for configuration management of compute instances. The reference config configures Ubuntu operating system level settings needed before installing kubernetes.

    #cloud-config
    packages:
      - curl
      - jq
    runcmd:
      - sysctl -w vm.overcommit_memory=1
      - sysctl -w kernel.panic=10
      - sysctl -w kernel.panic_on_oops=1
      - curl https://releases.rancher.com/install-docker/18.09.sh | sh
      - usermod -aG docker ubuntu
      - return=1; while [ $return != 0 ]; do sleep 2; docker ps; return=$?; done
      - addgroup --gid 52034 etcd
      - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd
    write_files:
      - path: /etc/sysctl.d/kubelet.conf
        owner: root:root
        permissions: "0644"
        content: |
          vm.overcommit_memory=1
          kernel.panic=10
          kernel.panic_on_oops=1
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html index 08d345e2c09..bc17bfe1db9 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html +++ b/v2.0-v2.4/reference-guides/rancher-security/rancher-v2.4-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ CIS Benchmark Rancher Self-Assessment Guide - v2.4 | Rancher Manager - + @@ -234,7 +234,7 @@ Create a PSP as described in the Kubernetes documentation, ensuring that the Follow the documentation and create NetworkPolicy objects as you need them.

    Audit Script: 5.3.2.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-"/root/.kube/config"}

    kubectl version > /dev/null
    if [ $? -ne 0 ]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    for namespace in $(kubectl get namespaces -A -o json | jq -r '.items[].metadata.name'); do
      policy_count=$(kubectl get networkpolicy -n ${namespace} -o json | jq '.items | length')
      if [ ${policy_count} -eq 0 ]; then
        echo "fail: ${namespace}"
        exit 1
      fi
    done

    echo "pass"

    Audit Execution:

    ./5.3.2.sh

    Expected result:

    'pass' is present

    5.6 General Policies​

    5.6.4 The default namespace should not be used (Scored)​

    Result: PASS

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Audit Script: 5.6.4.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-/root/.kube/config}

    kubectl version > /dev/null
    if [[ $? -gt 0 ]]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    default_resources=$(kubectl get all -o json | jq --compact-output '.items[] | select((.kind == "Service") and (.metadata.name == "kubernetes") and (.metadata.namespace == "default") | not)' | wc -l)

    echo "--count=${default_resources}"

    Audit Execution:

    ./5.6.4.sh

    Expected result:

    '0' is equal to '0'
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rancher-security/security-advisories-and-cves.html b/v2.0-v2.4/reference-guides/rancher-security/security-advisories-and-cves.html index ebf179dc203..5b21ee7c709 100644 --- a/v2.0-v2.4/reference-guides/rancher-security/security-advisories-and-cves.html +++ b/v2.0-v2.4/reference-guides/rancher-security/security-advisories-and-cves.html @@ -5,13 +5,13 @@ Rancher CVEs and Resolutions | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher CVEs and Resolutions

    Rancher is committed to informing the community of security issues in our products. Rancher will publish CVEs (Common Vulnerabilities and Exposures) for issues we have resolved.

    IDDescriptionDateResolution
    CVE-2021-31999A vulnerability was discovered where a malicious Rancher user could craft an API request directed at the proxy for the Kubernetes API of a managed cluster to gain access to information they do not have access to. This is done by passing the "Impersonate-User" or "Impersonate-Group" header in the Connection header, which is then removed by the proxy. At this point, instead of impersonating the user and their permissions, the request will act as if it was from the Rancher management server, i.e. local server, and return the requested information. You are vulnerable if you are running any Rancher 2.x version. Only valid Rancher users who have some level of permission on the cluster can perform the request. There is no direct mitigation besides upgrading to the patched versions. You can limit wider exposure by ensuring all Rancher users are trusted.14 Jul 2021Rancher v2.5.9, Rancher v2.4.16
    CVE-2021-25318A vulnerability was discovered in Rancher where users were granted access to resources regardless of the resource's API group. For example Rancher should have allowed users access to apps.catalog.cattle.io, but instead incorrectly gave access to apps.*. You are vulnerable if you are running any Rancher 2.x version. The extent of the exploit increases if there are other matching CRD resources installed in the cluster. There is no direct mitigation besides upgrading to the patched versions.14 Jul 2021Rancher v2.5.9, Rancher v2.4.16
    CVE-2021-25320A vulnerability was discovered in Rancher where cloud credentials weren't being properly validated through the Rancher API. Specifically through a proxy designed to communicate with cloud providers. Any Rancher user that was logged-in and aware of a cloud credential ID that was valid for a given cloud provider could make requests against that cloud provider's API through the proxy API, and the cloud credential would be attached. You are vulnerable if you are running any Rancher 2.2.0 or above and use cloud credentials. The exploit is limited to valid Rancher users. There is no direct mitigation besides upgrading to the patched versions. You can limit wider exposure by ensuring all Rancher users are trusted.14 Jul 2021Rancher v2.5.9, Rancher v2.4.16
    CVE-2018-20321Any project member with access to the default namespace can mount the netes-default service account in a pod and then use that pod to execute administrative privileged commands against the Kubernetes cluster.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11 - Rolling back from these versions or greater have specific instructions.
    CVE-2019-6287Project members continue to get access to namespaces from projects that they were removed from if they were added to more than one project.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11
    CVE-2019-11202The default admin, that is shipped with Rancher, will be re-created upon restart of Rancher despite being explicitly deleted.16 Apr 2019Rancher v2.2.2, Rancher v2.1.9 and Rancher v2.0.14
    CVE-2019-12274Nodes using the built-in node drivers using a file path option allows the machine to read arbitrary files including sensitive ones from inside the Rancher server container.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-12303Project owners can inject extra fluentd logging configurations that makes it possible to read files or execute arbitrary commands inside the fluentd container. Reported by Tyler Welton from Untamed Theory.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-13209The vulnerability is known as a Cross-Site Websocket Hijacking attack. This attack allows an exploiter to gain access to clusters managed by Rancher with the roles/permissions of a victim. It requires that a victim to be logged into a Rancher server and then access a third-party site hosted by the exploiter. Once that is accomplished, the exploiter is able to execute commands against the Kubernetes API with the permissions and identity of the victim. Reported by Matt Belisle and Alex Stevenson from Workiva.15 Jul 2019Rancher v2.2.5, Rancher v2.1.11 and Rancher v2.0.16
    CVE-2019-14436The vulnerability allows a member of a project that has access to edit role bindings to be able to assign themselves or others a cluster level role granting them administrator access to that cluster. The issue was found and reported by Michal Lipinski at Nokia.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    CVE-2019-14435This vulnerability allows authenticated users to potentially extract otherwise private data out of IPs reachable from system service containers used by Rancher. This can include but not only limited to services such as cloud provider metadata services. Although Rancher allow users to configure whitelisted domains for system service access, this flaw can still be exploited by a carefully crafted HTTP request. The issue was found and reported by Matt Belisle and Alex Stevenson at Workiva.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/rke1-template-example-yaml.html b/v2.0-v2.4/reference-guides/rke1-template-example-yaml.html index e0379e33508..6da92b85666 100644 --- a/v2.0-v2.4/reference-guides/rke1-template-example-yaml.html +++ b/v2.0-v2.4/reference-guides/rke1-template-example-yaml.html @@ -5,13 +5,13 @@ RKE1 Example YAML | Rancher Manager - +
    Version: v2.0-v2.4

    RKE1 Example YAML

    Below is an example RKE template configuration file for reference.

    The YAML in the RKE template uses the same customization that is used when you create an RKE cluster. However, since the YAML is within the context of a Rancher provisioned RKE cluster, the customization from the RKE docs needs to be nested under the rancher_kubernetes_engine directive.

    #
    # Cluster Config
    #
    docker_root_dir: /var/lib/docker

    enable_cluster_alerting: false
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have alerting turned off by default,
    # but end users could still turn alerting
    # on or off.

    enable_cluster_monitoring: true
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have monitoring turned on
    # by default, but end users could still
    # turn monitoring on or off.

    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config: # Your RKE template config goes here.
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false
    windows_prefered_cluster: false
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/advanced-options.html b/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/advanced-options.html index 89003b91555..86e2abb155d 100644 --- a/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/advanced-options.html +++ b/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/advanced-options.html @@ -5,13 +5,13 @@ Advanced Options for Docker Installs | Rancher Manager - +
    Version: v2.0-v2.4

    Advanced Options for Docker Installs

    When installing Rancher, there are several advanced options that can be enabled:

    Custom CA Certificate​

    If you want to configure Rancher to use a CA root certificate to be used when validating services, you would start the Rancher container sharing the directory that contains the CA root certificate.

    Use the command example to start a Rancher container with your private CA certificates mounted.

    • The volume flag (-v) should specify the host directory containing the CA root certificates.
    • The environment variable flag (-e) in combination with SSL_CERT_DIR and directory declares an environment variable that specifies the mounted CA root certificates directory location inside the container.
    • Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE.
    • Mounting a host directory inside the container can be done using -v host-source-directory:container-destination-directory or --volume host-source-directory:container-destination-directory.

    The example below is based on having the CA root certificates in the /host/certs directory on the host and mounting this directory on /container/certs inside the Rancher container.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /host/certs:/container/certs \
      -e SSL_CERT_DIR="/container/certs" \
      rancher/rancher:latest

    API Audit Log​

    The API Audit Log records all the user and system transactions made through Rancher server.

    The API Audit Log writes to /var/log/auditlog inside the rancher container by default. Share that directory as a volume and set your AUDIT_LEVEL to enable the log.

    See API Audit Log for more information and options.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /var/log/rancher/auditlog:/var/log/auditlog \
      -e AUDIT_LEVEL=1 \
      rancher/rancher:latest

    TLS settings​

    Available as of v2.1.7

    To set a different TLS configuration, you can use the CATTLE_TLS_MIN_VERSION and CATTLE_TLS_CIPHERS environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e CATTLE_TLS_MIN_VERSION="1.0" \
      rancher/rancher:latest

    See TLS settings for more information and options.

    Air Gap​

    If you are visiting this page to complete an air gap installation, you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

    Example:

     <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

    Persistent Data​

    Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

    You can bind mount a host volume to this location to preserve data on the host it is running on:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /opt/rancher:/var/lib/rancher \
      rancher/rancher:latest

    Running rancher/rancher and rancher/rancher-agent on the Same Node​

    In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the rancher/rancher container.

    If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advise to expose for the rancher/rancher container.

    Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes.

    To change the host ports mapping, replace the following part -p 80:80 -p 443:443 with -p 8080:80 -p 8443:443:

    docker run -d --restart=unless-stopped \
      -p 8080:80 -p 8443:443 \
      rancher/rancher:latest
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html b/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html index 70f659faf5d..cb0808ecbca 100644 --- a/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html +++ b/v2.0-v2.4/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html @@ -5,13 +5,13 @@ HTTP Proxy Configuration | Rancher Manager - +
    Version: v2.0-v2.4

    HTTP Proxy Configuration

    If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.

    Make sure NO_PROXY contains the network addresses, network address ranges and domains that should be excluded from using the proxy.

    Environment variablePurpose
    HTTP_PROXYProxy address to use when initiating HTTP connection(s)
    HTTPS_PROXYProxy address to use when initiating HTTPS connection(s)
    NO_PROXYNetwork address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s)

    Note NO_PROXY must be in uppercase to use network range (CIDR) notation.

    Docker Installation​

    Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE. Required values for NO_PROXY in a Docker Installation are:

    • localhost
    • 127.0.0.1
    • 0.0.0.0
    • 10.0.0.0/8
    • cattle-system.svc
    • .svc
    • .cluster.local

    The example below is based on a proxy server accessible at http://192.168.0.1:3128, and excluding usage the proxy when accessing network range 192.168.10.0/24 and every hostname under the domain example.com.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e HTTP_PROXY="http://192.168.10.1:3128" \
      -e HTTPS_PROXY="http://192.168.10.1:3128" \
      -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,192.168.10.0/24,.svc,.cluster.local,example.com" \
      rancher/rancher:latest
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/system-tools.html b/v2.0-v2.4/reference-guides/system-tools.html index 8903120f2ab..4c568e452c9 100644 --- a/v2.0-v2.4/reference-guides/system-tools.html +++ b/v2.0-v2.4/reference-guides/system-tools.html @@ -5,14 +5,14 @@ System Tools | Rancher Manager - +
    Version: v2.0-v2.4

    System Tools

    System Tools is a tool to perform operational tasks on Rancher Launched Kubernetes clusters or installations of Rancher on an RKE cluster. The tasks include:

    • Collect logging and system metrics from nodes.
    • Remove Kubernetes resources created by Rancher.

    The following commands are available:

    CommandDescription
    logsCollect Kubernetes cluster component logs from nodes.
    statsStream system metrics from nodes.
    removeRemove Kubernetes resources created by Rancher.

    Download System Tools

    You can download the latest version of System Tools from the GitHub releases page. Download the version of system-tools for the OS that you are using to interact with the cluster.

    Operating SystemFilename
    MacOSsystem-tools_darwin-amd64
    Linuxsystem-tools_linux-amd64
    Windowssystem-tools_windows-amd64.exe

    After you download the tools, complete the following actions:

    1. Rename the file to system-tools.

    2. Give the file executable permissions by running the following command:

      Using Windows? The file is already an executable, you can skip this step.

      chmod +x system-tools

    Logs

    The logs subcommand will collect log files of core Kubernetes cluster components from nodes in Rancher-launched Kubernetes clusters or nodes on an RKE Kubernetes cluster that Rancher is installed on.. See Troubleshooting for a list of core Kubernetes cluster components.

    System Tools will use the provided kubeconfig file to deploy a DaemonSet, that will copy all the logfiles from the core Kubernetes cluster components and add them to a single tar file (cluster-logs.tar by default). If you only want to collect logging from a single node, you can specify the node by using --node NODENAME or -n NODENAME.

    Usage​

    ./system-tools_darwin-amd64 logs --kubeconfig <KUBECONFIG>

    The following are the options for the logs command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file.
    --output <FILENAME>, -o cluster-logs.tarName of the created tarball containing the logs. If no output filename is defined, the options defaults to cluster-logs.tar.
    --node <NODENAME>, -n node1Specify the nodes to collect the logs from. If no node is specified, logs from all nodes in the cluster will be collected.

    Stats

    The stats subcommand will display system metrics from nodes in Rancher-launched Kubernetes clusters or nodes in an RKE Kubernetes cluster that Rancher is installed on..

    System Tools will deploy a DaemonSet, and run a predefined command based on sar (System Activity Report) to show system metrics.

    Usage​

    ./system-tools_darwin-amd64 stats --kubeconfig <KUBECONFIG>

    The following are the options for the stats command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file.
    --node <NODENAME>, -n node1Specify the nodes to display the system metrics from. If no node is specified, logs from all nodes in the cluster will be displayed.
    --stats-command value, -s valueThe command to run to display the system metrics. If no command is defined, the options defaults to /usr/bin/sar -u -r -F 1 1.

    Remove

    Warning: This command will remove data from your etcd nodes. Make sure you have created a backup of etcd before executing the command.

    When you install Rancher on a Kubernetes cluster, it will create Kubernetes resources to run and to store configuration data. If you want to remove Rancher from your cluster, you can use the remove subcommand to remove the Kubernetes resources. When you use the remove subcommand, the following resources will be removed:

    • The Rancher deployment namespace (cattle-system by default).
    • Any serviceAccount, clusterRoles, and clusterRoleBindings that Rancher applied the cattle.io/creator:norman label to. Rancher applies this label to any resource that it creates as of v2.1.0.
    • Labels, annotations, and finalizers.
    • Rancher Deployment.
    • Machines, clusters, projects, and user custom resource deployments (CRDs).
    • All resources create under the management.cattle.io API Group.
    • All CRDs created by Rancher v2.x.

    Using 2.0.8 or Earlier?

    These versions of Rancher do not automatically delete the serviceAccount, clusterRole, and clusterRoleBindings resources after the job runs. You'll have to delete them yourself.

    Usage​

    When you run the command below, all the resources listed above will be removed from the cluster.

    Warning: This command will remove data from your etcd nodes. Make sure you have created a backup of etcd before executing the command.

    ./system-tools remove --kubeconfig <KUBECONFIG> --namespace <NAMESPACE>

    The following are the options for the remove command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file
    --namespace <NAMESPACE>, -n cattle-systemRancher 2.x deployment namespace (<NAMESPACE>). If no namespace is defined, the options defaults to cattle-system.
    --forceSkips the interactive removal confirmation and removes the Rancher deployment without prompt.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/user-settings/api-keys.html b/v2.0-v2.4/reference-guides/user-settings/api-keys.html index 5eeb9207993..ec64a16170d 100644 --- a/v2.0-v2.4/reference-guides/user-settings/api-keys.html +++ b/v2.0-v2.4/reference-guides/user-settings/api-keys.html @@ -5,14 +5,14 @@ API Keys | Rancher Manager - +
    Version: v2.0-v2.4

    API Keys

    API Keys and User Authentication​

    If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI.

    An API key is also required for using Rancher CLI.

    API Keys are composed of four components:

    • Endpoint: This is the IP address and path that other applications use to send requests to the Rancher API.
    • Access Key: The token's username.
    • Secret Key: The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together.
    • Bearer Token: The token username and password concatenated together. Use this string for applications that prompt you for one authentication string.

    Creating an API Key​

    1. Select User Avatar > API & Keys from the User Settings menu in the upper-right.

    2. Click Add Key.

    3. Optional: Enter a description for the API key and select an expiration period or a scope. We recommend setting an expiration date.

      The API key won't be valid after expiration. Shorter expiration periods are more secure.

      Available as of v2.4.6 Expiration period will be bound by v3/settings/auth-token-max-ttl-minutes. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period.

      A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See Authorized Cluster Endpoints for more information.

    4. Click Create.

      Step Result: Your API Key is created. Your API Endpoint, Access Key, Secret Key, and Bearer Token are displayed.

      Use the Bearer Token to authenticate with Rancher CLI.

    5. Copy the information displayed to a secure location. This information is only displayed once, so if you lose your key, you'll have to make a new one.

    What's Next?​

    • Enter your API key information into the application that will send requests to the Rancher API.
    • Learn more about the Rancher endpoints and parameters by selecting View in API for an object in the Rancher UI.
    • API keys are used for API calls and Rancher CLI.

    Deleting API Keys​

    If you need to revoke an API key, delete it. You should delete API keys:

    • That may have been compromised.
    • That have expired.

    To delete an API, select the stale key and click Delete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/user-settings/manage-cloud-credentials.html b/v2.0-v2.4/reference-guides/user-settings/manage-cloud-credentials.html index 3c4325e712c..dd0ab7da642 100644 --- a/v2.0-v2.4/reference-guides/user-settings/manage-cloud-credentials.html +++ b/v2.0-v2.4/reference-guides/user-settings/manage-cloud-credentials.html @@ -5,13 +5,13 @@ Managing Cloud Credentials | Rancher Manager - +
    Version: v2.0-v2.4

    Managing Cloud Credentials

    Available as of v2.2.0

    When you create a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node.

    Node templates can use cloud credentials to access the credential information required to provision nodes in the infrastructure providers. The same cloud credential can be used by multiple node templates. By using a cloud credential, you do not have to re-enter access keys for the same cloud provider. Cloud credentials are stored as Kubernetes secrets.

    Cloud credentials are only used by node templates if there are fields marked as password. The default active node drivers have their account access fields marked as password, but there may be some inactive node drivers, which are not using them yet. These node drivers will not use cloud credentials.

    You can create cloud credentials in two contexts:

    All cloud credentials are bound to the user profile of who created it. They cannot be shared across users.

    Creating a Cloud Credential from User Settings​

    1. From your user settings, select User Avatar > Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. Select a Cloud Credential Type from the drop down. The values of this dropdown is based on the active node drivers in Rancher.
    5. Based on the selected cloud credential type, enter the required values to authenticate with the infrastructure provider.
    6. Click Create.

    Result: The cloud credential is created and can immediately be used to create node templates.

    Updating a Cloud Credential​

    When access credentials are changed or compromised, updating a cloud credential allows you to rotate those credentials while keeping the same node template.

    1. From your user settings, select User Avatar > Cloud Credentials.
    2. Choose the cloud credential you want to edit and click the ⋮ > Edit.
    3. Update the credential information and click Save.

    Result: The cloud credential is updated with the new access credentials. All existing node templates using this cloud credential will automatically use the updated information whenever new nodes are added.

    Deleting a Cloud Credential​

    In order to delete cloud credentials, there must not be any node template associated with it. If you are unable to delete the cloud credential, delete any node templates that are still associated to that cloud credential.

    1. From your user settings, select User Avatar > Cloud Credentials.

    2. You can either individually delete a cloud credential or bulk delete.

      • To individually delete one, choose the cloud credential you want to edit and click the ⋮ > Delete.
      • To bulk delete cloud credentials, select one or more cloud credentials from the list. Click Delete.

    3. Confirm that you want to delete these cloud credentials.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/user-settings/manage-node-templates.html b/v2.0-v2.4/reference-guides/user-settings/manage-node-templates.html index 85b0325ee4d..9cb7c5a5d5e 100644 --- a/v2.0-v2.4/reference-guides/user-settings/manage-node-templates.html +++ b/v2.0-v2.4/reference-guides/user-settings/manage-node-templates.html @@ -5,13 +5,13 @@ Managing Node Templates | Rancher Manager - +
    Version: v2.0-v2.4

    Managing Node Templates

    When you provision a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node. You can create node templates in two contexts:

    When you create a node template, it is bound to your user profile. Node templates cannot be shared among users. You can delete stale node templates that you no longer user from your user settings.

    Creating a Node Template from User Settings​

    1. From your user settings, select User Avatar > Node Templates.
    2. Click Add Template.
    3. Select one of the cloud providers available. Then follow the instructions on screen to configure the template.

    Result: The template is configured. You can use the template later when you provision a node pool cluster.

    Updating a Node Template​

    1. From your user settings, select User Avatar > Node Templates.

    2. Choose the node template that you want to edit and click the ⋮ > Edit.

      note

      As of v2.2.0, the default active node drivers and any node driver, that has fields marked as password, are required to use cloud credentials. If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it.

    3. Edit the required information and click Save.

    Result: The node template is updated. All node pools using this node template will automatically use the updated information when new nodes are added.

    Cloning Node Templates​

    When creating new node templates from your user settings, you can clone an existing template and quickly update its settings rather than creating a new one from scratch. Cloning templates saves you the hassle of re-entering access keys for the cloud provider.

    1. From your user settings, select User Avatar > Node Templates.
    2. Find the template you want to clone. Then select ⋮ > Clone.
    3. Complete the rest of the form.

    Result: The template is cloned and configured. You can use the template later when you provision a node pool cluster.

    Deleting a Node Template​

    When you no longer use a node template, you can delete it from your user settings.

    1. From your user settings, select User Avatar > Node Templates.
    2. Select one or more template from the list. Then click Delete. Confirm the delete when prompted.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/user-settings/user-preferences.html b/v2.0-v2.4/reference-guides/user-settings/user-preferences.html index 2736b6f6c78..1240fd68fac 100644 --- a/v2.0-v2.4/reference-guides/user-settings/user-preferences.html +++ b/v2.0-v2.4/reference-guides/user-settings/user-preferences.html @@ -5,13 +5,13 @@ User Preferences | Rancher Manager - +
    Version: v2.0-v2.4

    User Preferences

    Each user can choose preferences to personalize their Rancher experience. To change preference settings, open the User Settings menu and then select Preferences.

    Theme​

    Choose your background color for the Rancher UI. If you choose Auto, the background color changes from light to dark at 6 PM, and then changes back at 6 AM.

    My Account​

    This section displays the Name (your display name) and Username (your login) used for your session. To change your login's current password, click the Change Password button.

    Table Row per Page​

    On pages that display system objects like clusters or deployments in a table, you can set the number of objects that display on the page before you must paginate. The default setting is 50.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/reference-guides/v1.6-migration/migration-tools-cli-reference.html b/v2.0-v2.4/reference-guides/v1.6-migration/migration-tools-cli-reference.html index 4bb4594d2b1..cc2a241cbb5 100644 --- a/v2.0-v2.4/reference-guides/v1.6-migration/migration-tools-cli-reference.html +++ b/v2.0-v2.4/reference-guides/v1.6-migration/migration-tools-cli-reference.html @@ -5,13 +5,13 @@ Migration Tools CLI Reference | Rancher Manager - +
    Version: v2.0-v2.4

    Migration Tools CLI Reference

    The migration-tools CLI includes multiple commands and options to assist your migration from Rancher v1.6 to Rancher v2.x.

    Download​

    The migration-tools CLI for your platform can be downloaded from our GitHub releases page. The tool is available for Linux, Mac, and Windows platforms.

    Usage​

    migration-tools [global options] command [command options] [arguments...]

    Migration Tools Global Options​

    The migration-tools CLI includes a handful of global options.

    Global OptionDescription
    --debugEnables debug logging.
    --log <VALUE>Outputs logs to the path you enter.
    --help, -hDisplays a list of all commands available.
    --version, -vPrints the version of migration-tools CLI in use.

    Commands and Command Options​

    Migration-Tools Export Reference​

    The migration-tools export command exports all stacks from your Rancher v1.6 server into Compose files.

    Options​

    OptionRequired?Description
    --url <VALUE>✓Rancher API endpoint URL (<RANCHER_URL>).
    --access-key <VALUE>✓Rancher API access key. Using an account API key exports all stacks from all cattle environments (<RANCHER_ACCESS_KEY>).
    --secret-key <VALUE>✓Rancher API secret key associated with the access key. (<RANCHER_SECRET_KEY>).
    --export-dir <VALUE>Base directory that Compose files export to under sub-directories created for each environment/stack (default: Export).
    --all, --aExport all stacks. Using this flag exports any stack in a state of inactive, stopped, or removing.
    --system, --sExport system and infrastructure stacks.

    Usage​

    Execute the following command, replacing each placeholder with your values. The access key and secret key are Account API keys, which will allow you to export from all Cattle environments.

    migration-tools export --url <RANCHER_URL> --access-key <RANCHER_ACCESS_KEY> --secret-key <RANCHER_SECRET_KEY> --export-dir <EXPORT_DIR>

    Result: The migration-tools CLI exports Compose files for each stack in every Cattle environments in the --export-dir directory. If you omitted this option, the files are saved to your current directory.

    Migration-Tools Parse Reference​

    The migration-tools parse command parses the Compose files for a stack and uses Kompose to generate an equivalent Kubernetes manifest. It also outputs an output.txt file, which lists all the constructs that will need manual intervention in order to be converted to Kubernetes.

    Options​

    OptionRequired?Description
    --docker-file <VALUE>Parses Docker Compose file to output Kubernetes manifest(default: docker-compose.yml)
    --output-file <VALUE>Name of file that outputs listing checks and advice for conversion (default: output.txt).
    --rancher-file <VALUE>Parses Rancher Compose file to output Kubernetes manifest(default: rancher-compose.yml)

    Subcommands​

    SubcommandDescription
    help, hShows a list of options available for use with preceding command.

    Usage​

    Execute the following command, replacing each placeholder with the absolute path to your Stack's Compose files. For each stack, you'll have to re-run the command for each pair of Compose files that was exported.

    migration-tools parse --docker-file <DOCKER_COMPOSE_ABSOLUTE_PATH> --rancher-file <RANCHER_COMPOSE_ABSOLUTE_PATH>

    Note: If you omit the --docker-file and --rancher-file options from your command, the migration-tools CLI checks its home directory for these Compose files.

    Result: The migration-tools CLI parses your Compose files and outputs Kubernetes manifest specs as well as an output.txt file. For each service in the stack, a Kubernetes manifest is created and named the same as your service. The output.txt file lists all constructs for each service in docker-compose.yml that requires special handling to be successfully migrated to Rancher v2.x. Each construct links to the relevant blog articles on how to implement it in Rancher v2.x.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.0.html b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.0.html index d9b696abd1a..71a6bf46f1a 100644 --- a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.0.html +++ b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.0.html @@ -5,13 +5,13 @@ Rancher v2.3.0 | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher v2.3.0

    Self Assessment Guide​

    This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

    Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
    Self Assessment Guide v2.3Rancher v2.3.0-2.3.2Hardening Guide v2.3Kubernetes 1.15Benchmark v1.4.1

    Hardening Guide​

    This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

    Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
    Hardening Guide v2.3Rancher v2.3.0-v2.3.2Benchmark v1.4.1Kubernetes 1.15
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.3.html b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.3.html index 407628d8131..c5a39ef2c39 100644 --- a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.3.html +++ b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.3.html @@ -5,13 +5,13 @@ Rancher v2.3.3 | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher v2.3.3

    Self Assessment Guide​

    This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

    Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
    Self Assessment Guide v2.3.3Rancher v2.3.3Hardening Guide v2.3.3Kubernetes v1.16Benchmark v1.4.1

    Hardening Guide​

    This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

    Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
    Hardening Guide v2.3.3Rancher v2.3.3Benchmark v1.4.1Kubernetes 1.14, 1.15, and 1.16
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.5.html b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.5.html index fb63041e361..8eb70e58c89 100644 --- a/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.5.html +++ b/v2.0-v2.4/security/rancher-2.3.x/rancher-v2.3.5.html @@ -5,13 +5,13 @@ Rancher v2.3.5 | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher v2.3.5

    Self Assessment Guide​

    This guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark:

    Self Assessment Guide VersionRancher VersionHardening Guide VersionKubernetes VersionCIS Benchmark Version
    Self Assessment Guide v2.3.5Rancher v2.3.5Hardening Guide v2.3.5Kubernetes v1.15Benchmark v1.5

    Hardening Guide​

    This hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher:

    Hardening Guide VersionRancher VersionCIS Benchmark VersionKubernetes Version
    Hardening Guide v2.3.5Rancher v2.3.5Benchmark v1.5Kubernetes 1.15
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/security/security-scan.html b/v2.0-v2.4/security/security-scan.html index 80041eeb1d0..6081c47a5da 100644 --- a/v2.0-v2.4/security/security-scan.html +++ b/v2.0-v2.4/security/security-scan.html @@ -5,13 +5,13 @@ Security Scans | Rancher Manager - +
    Version: v2.0-v2.4

    Security Scans

    The documentation about CIS security scans has moved here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting.html b/v2.0-v2.4/troubleshooting.html index 24a461bfc45..f976940bd00 100644 --- a/v2.0-v2.4/troubleshooting.html +++ b/v2.0-v2.4/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
    Version: v2.0-v2.4

    Troubleshooting

    This section contains information to help you troubleshoot issues when using Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html index c6816c60c42..8d2e4b6ec65 100644 --- a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html +++ b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html @@ -5,13 +5,13 @@ Troubleshooting Controlplane Nodes | Rancher Manager - +
    Version: v2.0-v2.4

    Troubleshooting Controlplane Nodes

    This section applies to nodes with the controlplane role.

    Check if the Controlplane Containers are Running

    There are three specific containers launched on nodes with the controlplane role:

    • kube-apiserver
    • kube-controller-manager
    • kube-scheduler

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kube-apiserver|kube-controller-manager|kube-scheduler'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    26c7159abbcc        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-apiserver
    f3d287ca4549        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-scheduler
    bdf3898b8063        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-controller-manager

    Controlplane Container Logging

    Note: If you added multiple nodes with the controlplane role, both kube-controller-manager and kube-scheduler use a leader election process to determine the leader. Only the current leader will log the performed actions. See Kubernetes leader election how to retrieve the current leader.

    The logging of the containers can contain information on what the problem could be.

    docker logs kube-apiserver
    docker logs kube-controller-manager
    docker logs kube-scheduler
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html index 656508ce30c..c2db8062ffa 100644 --- a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html +++ b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html @@ -5,13 +5,13 @@ Troubleshooting etcd Nodes | Rancher Manager - +
    Version: v2.0-v2.4

    Troubleshooting etcd Nodes

    This section contains commands and tips for troubleshooting nodes with the etcd role.

    Checking if the etcd Container is Running​

    The container for etcd should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=etcd$

    Example output:

    CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS              PORTS               NAMES
    605a124503b9        rancher/coreos-etcd:v3.2.18   "/usr/local/bin/et..."   2 hours ago         Up 2 hours                              etcd

    etcd Container Logging​

    The logging of the container can contain information on what the problem could be.

    docker logs etcd
    LogExplanation
    health check for peer xxx could not connect: dial tcp IP:2380: getsockopt: connection refusedA connection to the address shown on port 2380 cannot be established. Check if the etcd container is running on the host with the address shown.
    xxx is starting a new election at term xThe etcd cluster has lost its quorum and is trying to establish a new leader. This can happen when the majority of the nodes running etcd go down/unreachable.
    connection error: desc = "transport: Error while dialing dial tcp 0.0.0.0:2379: i/o timeout"; Reconnecting to {0.0.0.0:2379 0 <nil>}The host firewall is preventing network communication.
    rafthttp: request cluster ID mismatchThe node with the etcd instance logging rafthttp: request cluster ID mismatch is trying to join a cluster that has already been formed with another peer. The node should be removed from the cluster, and re-added.
    rafthttp: failed to find memberThe cluster state (/var/lib/etcd) contains wrong information to join the cluster. The node should be removed from the cluster, the state directory should be cleaned and the node should be re-added.

    etcd Cluster and Connectivity Checks​

    The address where etcd is listening depends on the address configuration of the host etcd is running on. If an internal address is configured for the host etcd is running on, the endpoint for etcdctl needs to be specified explicitly. If any of the commands respond with Error: context deadline exceeded, the etcd instance is unhealthy (either quorum is lost or the instance is not correctly joined in the cluster)

    Check etcd Members on all Nodes​

    Output should contain all the nodes with the etcd role and the output should be identical on all nodes.

    Command:

    docker exec etcd etcdctl member list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list"

    Example output:

    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001

    Check Endpoint Status​

    The values for RAFT TERM should be equal and RAFT INDEX should be not be too far apart from each other.

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 | 333ef673fc4add56 |  3.2.18 |   24 MB |     false |        72 |      66887 |
    | https://IP:2379 | 5feed52d940ce4cf |  3.2.18 |   24 MB |      true |        72 |      66887 |
    | https://IP:2379 | db6b3bdb559a848d |  3.2.18 |   25 MB |     false |        72 |      66887 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Check Endpoint Health​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint health

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint health --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")

    Example output:

    https://IP:2379 is healthy: successfully committed proposal: took = 2.113189ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.649963ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.451201ms

    Check Connectivity on Port TCP/2379​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5"); do
       echo "Validating connection to ${endpoint}/health"
       docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5"); do
      echo "Validating connection to ${endpoint}/health";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Example output:

    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}

    Check Connectivity on Port TCP/2380​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Example output:

    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}

    etcd Alarms​

    etcd will trigger alarms, for instance when it runs out of space.

    Command:

    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output when NOSPACE alarm is triggered:

    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE

    etcd Space Errors​

    Related error messages are etcdserver: mvcc: database space exceeded or applying raft message exceeded backend quota. Alarm NOSPACE will be triggered.

    Resolutions:

    Compact the Keyspace​

    Command:

    rev=$(docker exec etcd etcdctl endpoint status --write-out json | egrep -o '"revision":[0-9]*' | egrep -o '[0-9]*')
    docker exec etcd etcdctl compact "$rev"

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    rev=$(docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT endpoint status --write-out json | egrep -o '\"revision\":[0-9]*' | egrep -o '[0-9]*'")
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT compact \"$rev\""

    Example output:

    compacted revision xxx

    Defrag All etcd Members​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl defrag

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl defrag --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")"

    Example output:

    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]

    Check Endpoint Status​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table"

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 |  e973e4419737125 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | 4a509c997b26c206 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | b217e736575e9dd3 |  3.2.18 |  553 kB |      true |        32 |    2449410 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Disarm Alarm​

    After verifying that the DB size went down after compaction and defragmenting, the alarm needs to be disarmed for etcd to allow writes again.

    Command:

    docker exec etcd etcdctl alarm list
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm disarm"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output:

    docker exec etcd etcdctl alarm list
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Log Level​

    The log level of etcd can be changed dynamically via the API. You can configure debug logging using the commands below.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    To reset the log level back to the default (INFO), you can use the following command.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    etcd Content​

    If you want to investigate the contents of your etcd, you can either watch streaming events or you can query etcd directly, see below for examples.

    Watch Streaming Events​

    Command:

    docker exec etcd etcdctl watch --prefix /registry

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT watch --prefix /registry

    If you only want to see the affected keys (and not the binary data), you can append | grep -a ^/registry to the command to filter for keys only.

    Query etcd Directly​

    Command:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT get /registry --prefix=true --keys-only

    You can process the data to get a summary of count per key, using the command below:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only | grep -v ^$ | awk -F'/' '{ if ($3 ~ /cattle.io/) {h[$3"/"$4]++} else { h[$3]++ }} END { for(k in h) print h[k], k }' | sort -nr

    Replacing Unhealthy etcd Nodes​

    When a node in your etcd cluster becomes unhealthy, the recommended approach is to fix or remove the failed or unhealthy node before adding a new etcd node to the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html index 75a6b715a6b..9bae82ffc59 100644 --- a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html +++ b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html @@ -5,13 +5,13 @@ Troubleshooting nginx-proxy | Rancher Manager - +
    Version: v2.0-v2.4

    Troubleshooting nginx-proxy

    The nginx-proxy container is deployed on every node that does not have the controlplane role. It provides access to all the nodes with the controlplane role by dynamically generating the NGINX configuration based on available nodes with the controlplane role.

    Check if the Container is Running

    The container is called nginx-proxy and should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=nginx-proxy

    Example output:

    docker ps -a -f=name=nginx-proxy
    CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS               NAMES
    c3e933687c0e        rancher/rke-tools:v0.1.15   "nginx-proxy CP_HO..."   3 hours ago         Up 3 hours                              nginx-proxy

    Check Generated NGINX Configuration

    The generated configuration should include the IP addresses of the nodes with the controlplane role. The configuration can be checked using the following command:

    docker exec nginx-proxy cat /etc/nginx/nginx.conf

    Example output:

    error_log stderr notice;

    worker_processes auto;
    events {
      multi_accept on;
      use epoll;
      worker_connections 1024;
    }

    stream {
            upstream kube_apiserver {

                server ip_of_controlplane_node1:6443;

                server ip_of_controlplane_node2:6443;

            }

            server {
                listen        6443;
                proxy_pass    kube_apiserver;
                proxy_timeout 30;
                proxy_connect_timeout 2s;

            }

    }

    nginx-proxy Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs nginx-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html index 79f2e0d3fe4..007fc112022 100644 --- a/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html +++ b/v2.0-v2.4/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html @@ -5,13 +5,13 @@ Troubleshooting Worker Nodes and Generic Components | Rancher Manager - +
    Version: v2.0-v2.4

    Troubleshooting Worker Nodes and Generic Components

    This section applies to every node as it includes components that run on nodes with any role.

    Check if the Containers are Running

    There are two specific containers launched on nodes with the worker role:

    • kubelet
    • kube-proxy

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kubelet|kube-proxy'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    158d0dcc33a5        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-proxy
    a30717ecfb55        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kubelet

    Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs kubelet
    docker logs kube-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/dns.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/dns.html index 458e55329a3..f136e852f2f 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/dns.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/dns.html @@ -5,13 +5,13 @@ DNS | Rancher Manager - +
    Version: v2.0-v2.4

    DNS

    The commands/steps listed on this page can be used to check name resolution issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Before running the DNS checks, check the default DNS provider for your cluster and make sure that the overlay network is functioning correctly as this can also be the reason why DNS resolution (partly) fails.

    Check if DNS pods are running​

    kubectl -n kube-system get pods -l k8s-app=kube-dns

    Example output when using CoreDNS:

    NAME                       READY   STATUS    RESTARTS   AGE
    coredns-799dffd9c4-6jhlz   1/1     Running   0          76m

    Example output when using kube-dns:

    NAME                        READY   STATUS    RESTARTS   AGE
    kube-dns-5fd74c7488-h6f7n   3/3     Running   0          4m13s

    Check if the DNS service is present with the correct cluster-ip​

    kubectl -n kube-system get svc -l k8s-app=kube-dns
    NAME               TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)         AGE
    service/kube-dns   ClusterIP   10.43.0.10   <none>        53/UDP,53/TCP   4m13s

    Check if domain names are resolving​

    Check if internal cluster names are resolving (in this example, kubernetes.default), the IP shown after Server: should be the same as the CLUSTER-IP from the kube-dns service.

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes.default

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      kubernetes.default
    Address 1: 10.43.0.1 kubernetes.default.svc.cluster.local
    pod "busybox" deleted

    Check if external names are resolving (in this example, www.google.com)

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup www.google.com

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      www.google.com
    Address 1: 2a00:1450:4009:80b::2004 lhr35s04-in-x04.1e100.net
    Address 2: 216.58.211.100 ams15s32-in-f4.1e100.net
    pod "busybox" deleted

    If you want to check resolving of domain names on all of the hosts, execute the following steps:

    1. Save the following file as ds-dnstest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: dnstest
      spec:
        selector:
            matchLabels:
              name: dnstest
        template:
          metadata:
            labels:
              name: dnstest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: busybox:1.28
              imagePullPolicy: Always
              name: alpine
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f ds-dnstest.yml

    3. Wait until kubectl rollout status ds/dnstest -w returns: daemon set "dnstest" successfully rolled out.

    4. Configure the environment variable DOMAIN to a fully qualified domain name (FQDN) that the host should be able to resolve (www.google.com is used as an example) and run the following command to let each container on every host resolve the configured domain name (it's a single line command).

      export DOMAIN=www.google.com; echo "=> Start DNS resolve test"; kubectl get pods -l name=dnstest --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do kubectl exec $pod -- /bin/sh -c "nslookup $DOMAIN > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $host cannot resolve $DOMAIN; fi; done; echo "=> End DNS resolve test"

    5. When this command has finished running, the output indicating everything is correct is:

      => Start DNS resolve test
      => End DNS resolve test

    If you see error in the output, that means that the mentioned host(s) is/are not able to resolve the given FQDN.

    Example error output of a situation where host with IP 209.97.182.150 had the UDP ports blocked.

    => Start DNS resolve test
    command terminated with exit code 1
    209.97.182.150 cannot resolve www.google.com
    => End DNS resolve test

    Cleanup the alpine DaemonSet by running kubectl delete ds/dnstest.

    CoreDNS specific​

    Check CoreDNS logging​

    kubectl -n kube-system logs -l k8s-app=kube-dns

    Check configuration​

    CoreDNS configuration is stored in the configmap coredns in the kube-system namespace.

    kubectl -n kube-system get configmap coredns -o go-template={{.data.Corefile}}

    Check upstream nameservers in resolv.conf​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for CoreDNS. You can check this file on the host or run the following Pod with dnsPolicy set to Default, which will inherit the /etc/resolv.conf from the host it is running on.

    kubectl run -i --restart=Never --rm test-${RANDOM} --image=ubuntu --overrides='{"kind":"Pod", "apiVersion":"v1", "spec": {"dnsPolicy":"Default"}}' -- sh -c 'cat /etc/resolv.conf'

    Enable query logging​

    Enabling query logging can be done by enabling the log plugin in the Corefile configuration in the configmap coredns. You can do so by using kubectl -n kube-system edit configmap coredns or use the command below to replace the configuration in place:

    kubectl get configmap -n kube-system coredns -o json | sed -e 's_loadbalance_log\\n    loadbalance_g' | kubectl apply -f -

    All queries will now be logged and can be checked using the command in Check CoreDNS logging.

    kube-dns specific​

    Check upstream nameservers in kubedns container​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for kube-dns. Sometimes the host will run a local caching DNS nameserver, which means the address in /etc/resolv.conf will point to an address in the loopback range (127.0.0.0/8) which will be unreachable by the container. In case of Ubuntu 18.04, this is done by systemd-resolved. Since Rancher v2.0.7, we detect if systemd-resolved is running, and will automatically use the /etc/resolv.conf file with the correct upstream nameservers (which is located at /run/systemd/resolve/resolv.conf).

    Use the following command to check the upstream nameservers used by the kubedns container:

    kubectl -n kube-system get pods -l k8s-app=kube-dns --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do echo "Pod ${pod} on host ${host}"; kubectl -n kube-system exec $pod -c kubedns cat /etc/resolv.conf; done

    Example output:

    Pod kube-dns-667c7cb9dd-z4dsf on host x.x.x.x
    nameserver 1.1.1.1
    nameserver 8.8.4.4

    If the output shows an address in the loopback range (127.0.0.0/8), you can correct this in two ways:

    • Make sure the correct nameservers are listed in /etc/resolv.conf on your nodes in the cluster, please consult your operating system documentation on how to do this. Make sure you execute this before provisioning a cluster, or reboot the nodes after making the modification.
    • Configure the kubelet to use a different file for resolving names, by using extra_args as shown below (where /run/resolvconf/resolv.conf is the file with the correct nameservers):
    services:
      kubelet:
        extra_args:
          resolv-conf: "/run/resolvconf/resolv.conf"

    Note: As the kubelet is running inside a container, the path for files located in /etc and /usr are in /host/etc and /host/usr inside the kubelet container.

    See Editing Cluster as YAML how to apply this change. When the provisioning of the cluster has finished, you have to remove the kube-dns pod to activate the new setting in the pod:

    kubectl delete pods -n kube-system -l k8s-app=kube-dns
    pod "kube-dns-5fd74c7488-6pwsf" deleted

    Try to resolve name again using Check if domain names are resolving.

    If you want to check the kube-dns configuration in your cluster (for example, to check if there are different upstream nameservers configured), you can run the following command to list the kube-dns configuration:

    kubectl -n kube-system get configmap kube-dns -o go-template='{{range $key, $value := .data}}{{ $key }}{{":"}}{{ $value }}{{"\n"}}{{end}}'

    Example output:

    upstreamNameservers:["1.1.1.1"]
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html index a4c494a95a1..d310970a140 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html @@ -5,13 +5,13 @@ Kubernetes resources | Rancher Manager - +
    Version: v2.0-v2.4

    Kubernetes resources

    The commands/steps listed on this page can be used to check the most important Kubernetes resources and apply to Rancher Launched Kubernetes clusters.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Nodes​

    Get nodes​

    Run the command below and check the following:

    • All nodes in your cluster should be listed, make sure there is not one missing.
    • All nodes should have the Ready status (if not in Ready state, check the kubelet container logs on that node using docker logs kubelet)
    • Check if all nodes report the correct version.
    • Check if OS/Kernel/Docker values are shown as expected (possibly you can relate issues due to upgraded OS/Kernel/Docker)
    kubectl get nodes -o wide

    Example output:

    NAME             STATUS   ROLES          AGE   VERSION   INTERNAL-IP      EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME
    controlplane-0   Ready    controlplane   31m   v1.13.5   138.68.188.91    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    etcd-0           Ready    etcd           31m   v1.13.5   138.68.180.33    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    worker-0         Ready    worker         30m   v1.13.5   139.59.179.88    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5

    Get node conditions​

    Run the command below to list nodes with Node Conditions

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{end}}'

    Run the command below to list nodes with Node Conditions that are active that could prevent normal operation.

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{if ne .type "Ready"}}{{if eq .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{else}}{{if ne .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{": "}}{{.status}}{{"\n"}}{{end}}{{end}}{{end}}{{end}}'

    Example output:

    worker-0: DiskPressure:True

    Kubernetes leader election​

    Kubernetes Controller Manager leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-controller-manager endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-controller-manager -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Kubernetes Scheduler leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-scheduler endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-scheduler -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Ingress Controller​

    The default Ingress Controller is NGINX and is deployed as a DaemonSet in the ingress-nginx namespace. The pods are only scheduled to nodes with the worker role.

    Check if the pods are running on all nodes:

    kubectl -n ingress-nginx get pods -o wide

    Example output:

    kubectl -n ingress-nginx get pods -o wide
    NAME                                    READY     STATUS    RESTARTS   AGE       IP               NODE
    default-http-backend-797c5bc547-kwwlq   1/1       Running   0          17m       x.x.x.x          worker-1
    nginx-ingress-controller-4qd64          1/1       Running   0          14m       x.x.x.x          worker-1
    nginx-ingress-controller-8wxhm          1/1       Running   0          13m       x.x.x.x          worker-0

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n ingress-nginx describe pods -l app=ingress-nginx

    Pod container logs​

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    Namespace events​

    kubectl -n ingress-nginx get events

    Debug logging​

    To enable debug logging:

    kubectl -n ingress-nginx patch ds nginx-ingress-controller --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--v=5"}]'

    Check configuration​

    Retrieve generated configuration in each pod:

    kubectl -n ingress-nginx get pods -l app=ingress-nginx --no-headers -o custom-columns=.NAME:.metadata.name | while read pod; do kubectl -n ingress-nginx exec $pod -- cat /etc/nginx/nginx.conf; done

    Rancher agents​

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes (cluster provisioning via cattle-node-agent) is done through Rancher agents.

    cattle-node-agent​

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent

    Jobs and Pods​

    Check that pods or jobs have status Running/Completed​

    To check, run the command:

    kubectl get pods --all-namespaces

    If a pod is not in Running state, you can dig into the root cause by running:

    Describe pod​

    kubectl describe pod POD_NAME -n NAMESPACE

    Pod container logs​

    kubectl logs POD_NAME -n NAMESPACE

    If a job is not in Completed state, you can dig into the root cause by running:

    Describe job​

    kubectl describe job JOB_NAME -n NAMESPACE

    Logs from the containers of pods of the job​

    kubectl logs -l job-name=JOB_NAME -n NAMESPACE

    Evicted pods​

    Pods can be evicted based on eviction signals.

    Retrieve a list of evicted pods (podname and namespace):

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}'

    To delete all evicted pods:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace delete pod $epod; done

    Retrieve a list of evicted pods, scheduled node and the reason:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace get pod $epod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,MSG:.status.message; done

    Job does not complete​

    If you have enabled Istio, and you are having issues with a Job you deployed not completing, you will need to add an annotation to your pod using these steps.

    Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. This is a temporary workaround and will disable Istio for any traffic to/from the annotated Pod. Keep in mind this may not allow you to continue to use a Job for integration testing, as the Job will not have access to the service mesh.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/logging.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/logging.html index 15ba510f4fe..83f57310932 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/logging.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/logging.html @@ -5,13 +5,13 @@ Logging | Rancher Manager - +
    Version: v2.0-v2.4

    Logging

    The following log levels are used in Rancher:

    NameDescription
    infoLogs informational messages. This is the default log level.
    debugLogs more detailed messages that can be used to debug.
    traceLogs very detailed messages on internal functions. This is very verbose and can contain sensitive information.

    How to configure a log level​

    • Kubernetes install
    • Configure debug log level
    $ KUBECONFIG=./kube_config_rancher-cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set debug; done
    OK
    OK
    OK
    $ kubectl -n cattle-system logs -l app=rancher -c rancher
    • Configure info log level
    $ KUBECONFIG=./kube_config_rancher-cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set info; done
    OK
    OK
    OK
    • Docker Install
    • Configure debug log level
    $ docker exec -ti <container_id> loglevel --set debug
    OK
    $ docker logs -f <container_id>
    • Configure info log level
    $ docker exec -ti <container_id> loglevel --set info
    OK
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/networking.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/networking.html index 86c65affd06..fdb80cb613f 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/networking.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
    Version: v2.0-v2.4

    Networking

    The commands/steps listed on this page can be used to check networking related issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Double check if all the required ports are opened in your (host) firewall​

    Double check if all the required ports are opened in your (host) firewall. The overlay network uses UDP in comparison to all other required ports which are TCP.

    Check if overlay network is functioning correctly​

    The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from NODE_1 to NODE_2. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.

    To test the overlay network, you can launch the following DaemonSet definition. This will run a swiss-army-knife container on every host (image was developed by Rancher engineers and can be found here: https://github.com/rancherlabs/swiss-army-knife), which we will use to run a ping test between containers on all hosts.

    Note: This container does not support ARM nodes, such as a Raspberry Pi. This will be seen in the pod logs as exec user process caused: exec format error.

    1. Save the following file as overlaytest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: overlaytest
      spec:
        selector:
            matchLabels:
              name: overlaytest
        template:
          metadata:
            labels:
              name: overlaytest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: rancherlabs/swiss-army-knife
              imagePullPolicy: Always
              name: overlaytest
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f overlaytest.yml

    3. Wait until kubectl rollout status ds/overlaytest -w returns: daemon set "overlaytest" successfully rolled out.

    4. Run the following script, from the same location. It will have each overlaytest container on every host ping each other:

      #!/bin/bash
      echo "=> Start network overlay test"
        kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' |
        while read spod shost
          do kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' |
          while read tip thost
            do kubectl --request-timeout='10s' exec $spod -c overlaytest -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1"
              RC=$?
              if [ $RC -ne 0 ]
                then echo FAIL: $spod on $shost cannot reach pod IP $tip on $thost
                else echo $shost can reach $thost
              fi
          done
        done
      echo "=> End network overlay test"

    5. When this command has finished running, it will output the state of each route:

      => Start network overlay test
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.7.3 on wk2
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.0.5 on cp1
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.2.12 on wk1
      command terminated with exit code 1
      FAIL: overlaytest-v4qkl on cp1 cannot reach pod IP 10.42.7.3 on wk2
      cp1 can reach cp1
      cp1 can reach wk1
      command terminated with exit code 1
      FAIL: overlaytest-xpxwp on wk1 cannot reach pod IP 10.42.7.3 on wk2
      wk1 can reach cp1
      wk1 can reach wk1
      => End network overlay test

      If you see error in the output, there is some issue with the route between the pods on the two hosts. In the above output the node wk2 has no connectivity over the overlay network. This could be because the required ports for overlay networking are not opened for wk2.

    6. You can now clean up the DaemonSet by running kubectl delete ds/overlaytest.

    Check if MTU is correctly configured on hosts and on peering/tunnel appliances/devices​

    When the MTU is incorrectly configured (either on hosts running Rancher, nodes in created/imported clusters or on appliances/devices in between), error messages will be logged in Rancher and in the agents, similar to:

    • websocket: bad handshake
    • Failed to connect to proxy
    • read tcp: i/o timeout

    See Google Cloud VPN: MTU Considerations for an example how to configure MTU correctly when using Google Cloud VPN between Rancher and cluster nodes.

    Resolved issues​

    Overlay network broken when using Canal/Flannel due to missing node annotations​

    GitHub issue#13644
    Resolved inv2.1.2

    To check if your cluster is affected, the following command will list nodes that are broken (this command requires jq to be installed):

    kubectl get nodes -o json | jq '.items[].metadata | select(.annotations["flannel.alpha.coreos.com/public-ip"] == null or .annotations["flannel.alpha.coreos.com/kube-subnet-manager"] == null or .annotations["flannel.alpha.coreos.com/backend-type"] == null or .annotations["flannel.alpha.coreos.com/backend-data"] == null) | .name'

    If there is no output, the cluster is not affected.

    System namespace pods network connectivity broken​

    Note: This applies only to Rancher upgrades from v2.0.6 or earlier to v2.0.7 or later. Upgrades from v2.0.7 to later version are unaffected.

    GitHub issue#15146

    If pods in system namespaces cannot communicate with pods in other system namespaces, you will need to follow the instructions in Upgrading to v2.0.7+ — Namespace Migration to restore connectivity. Symptoms include:

    • NGINX ingress controller showing 504 Gateway Time-out when accessed.
    • NGINX ingress controller logging upstream timed out (110: Connection timed out) while connecting to upstream when accessed.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/rancher-ha.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/rancher-ha.html index 3ec171cf08e..2957575eacd 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/rancher-ha.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/rancher-ha.html @@ -5,13 +5,13 @@ Rancher HA | Rancher Manager - +
    Version: v2.0-v2.4

    Rancher HA

    The commands/steps listed on this page can be used to check your Rancher Kubernetes Installation.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_rancher-cluster.yml).

    Check Rancher pods​

    Rancher pods are deployed as a Deployment in the cattle-system namespace.

    Check if the pods are running on all nodes:

    kubectl -n cattle-system get pods -l app=rancher -o wide

    Example output:

    NAME                       READY   STATUS    RESTARTS   AGE   IP          NODE
    rancher-7dbd7875f7-n6t5t   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qbj5k   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qw7wb   1/1     Running   0          8m    x.x.x.x     x.x.x.x

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n cattle-system describe pods -l app=rancher

    Pod container logs​

    kubectl -n cattle-system logs -l app=rancher

    Namespace events​

    kubectl -n cattle-system get events

    Check ingress​

    Ingress should have the correct HOSTS (showing the configured FQDN) and ADDRESS (host address(es) it will be routed to).

    kubectl -n cattle-system get ingress

    Example output:

    NAME      HOSTS                    ADDRESS                   PORTS     AGE
    rancher   rancher.yourdomain.com   x.x.x.x,x.x.x.x,x.x.x.x   80, 443   2m

    Check ingress controller logs​

    When accessing your configured Rancher FQDN does not show you the UI, check the ingress controller logging to see what happens when you try to access Rancher:

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    Leader election​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the cattle-controllers ConfigMap (in this example, rancher-7dbd7875f7-qbj5k).

    kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0}
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/registered-clusters.html b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/registered-clusters.html index a527a35fba2..f77d3341632 100644 --- a/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/registered-clusters.html +++ b/v2.0-v2.4/troubleshooting/other-troubleshooting-tips/registered-clusters.html @@ -5,13 +5,13 @@ Imported clusters | Rancher Manager - +
    Version: v2.0-v2.4

    Imported clusters

    The commands/steps listed on this page can be used to check clusters that you are importing or that are imported in Rancher.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kubeconfig_from_imported_cluster.yml)

    Rancher agents​

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes is done through Rancher agents.

    If the cattle-cluster-agent cannot connect to the configured server-url, the cluster will remain in Pending state, showing Waiting for full cluster configuration.

    cattle-node-agent​

    Note: Starting in Rancher 2.5 cattle-node-agents are only present in clusters created in Rancher with RKE.

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5.html b/v2.5.html index 9ec21a0c9c1..6959f788fbc 100644 --- a/v2.5.html +++ b/v2.5.html @@ -5,13 +5,13 @@ Rancher 2.5 | Rancher Manager - +
    Version: v2.5

    Rancher 2.5

    Rancher was originally built to work with multiple orchestrators, and it included its own orchestrator called Cattle. With the rise of Kubernetes in the marketplace, Rancher 2 exclusively deploys and manages Kubernetes clusters running anywhere, on any provider.

    Rancher can provision Kubernetes from a hosted provider, provision compute nodes and then install Kubernetes onto them, or import existing Kubernetes clusters running anywhere.

    Rancher adds significant value on top of Kubernetes, first by centralizing authentication and role-based access control (RBAC) for all of the clusters, giving global admins the ability to control cluster access from one location.

    It then enables detailed monitoring and alerting for clusters and their resources, ships logs to external providers, and integrates directly with Helm via the Application Catalog. If you have an external CI/CD system, you can plug it into Rancher, but if you don't, Rancher even includes Fleet to help you automatically deploy and upgrade workloads.

    Rancher is a complete container management platform for Kubernetes, giving you the tools to successfully run Kubernetes anywhere.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/backups/docker-installs.html b/v2.5/backups/docker-installs.html index 73b3de01809..ed87c59ddfb 100644 --- a/v2.5/backups/docker-installs.html +++ b/v2.5/backups/docker-installs.html @@ -5,13 +5,13 @@ Backup and Restore for Rancher Installed with Docker | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/cluster-provisioning/rke-clusters/options.html b/v2.5/cluster-provisioning/rke-clusters/options.html index 544493d0f97..4422ef516ed 100644 --- a/v2.5/cluster-provisioning/rke-clusters/options.html +++ b/v2.5/cluster-provisioning/rke-clusters/options.html @@ -5,13 +5,13 @@ RKE Cluster Configuration Reference | Rancher Manager - +
    Version: v2.5

    RKE Cluster Configuration Reference

    When Rancher installs Kubernetes, it uses RKE as the Kubernetes distribution.

    This section covers the configuration options that are available in Rancher for a new or existing RKE Kubernetes cluster.

    You can configure the Kubernetes options one of two ways:

    • Rancher UI: Use the Rancher UI to select options that are commonly customized when setting up a Kubernetes cluster.
    • Cluster Config File: Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

    The RKE cluster config options are nested under the rancher_kubernetes_engine_config directive. For more information, see the section about the cluster config file.

    Rancher UI Options​

    When creating a cluster using one of the options described in Rancher Launched Kubernetes, you can configure basic Kubernetes options using the Cluster Options section.

    Kubernetes Version​

    The version of Kubernetes installed on your cluster nodes. Rancher packages its own version of Kubernetes based on hyperkube.

    Network Provider​

    The Network Provider that the cluster uses. For more details on the different networking providers, please view our Networking FAQ.

    Note: After you launch the cluster, you cannot change your network provider. Therefore, choose which network provider you want to use carefully, as Kubernetes doesn't allow switching between network providers. Once a cluster is created with a network provider, changing network providers would require you tear down the entire cluster and all its applications.

    Out of the box, Rancher is compatible with the following network providers:

    Notes on Weave:

    When Weave is selected as network provider, Rancher will automatically enable encryption by generating a random password. If you want to specify the password manually, please see how to configure your cluster using a Config File and the Weave Network Plug-in Options.

    Project Network Isolation​

    Project network isolation is used to enable or disable communication between pods in different projects.

    To enable project network isolation as a cluster option, you will need to use any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.

    Kubernetes Cloud Providers​

    You can configure a Kubernetes cloud provider. If you want to use volumes and storage in Kubernetes, typically you must select the specific cloud provider in order to use it. For example, if you want to use Amazon EBS, you would need to select the aws cloud provider.

    Note: If the cloud provider you want to use is not listed as an option, you will need to use the config file option to configure the cloud provider. Please reference the RKE cloud provider documentation on how to configure the cloud provider.

    If you want to see all the configuration options for a cluster, please click Show advanced options on the bottom right. The advanced options are described below:

    Private registries​

    The cluster-level private registry configuration is only used for provisioning clusters.

    There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

    If your private registry requires credentials, you need to pass the credentials to Rancher by editing the cluster options for each cluster that needs to pull images from the registry.

    The private registry configuration option tells Rancher where to pull the system images or addon images that will be used in your cluster.

    • System images are components needed to maintain the Kubernetes cluster.
    • Add-ons are used to deploy several cluster components, including network plug-ins, the ingress controller, the DNS provider, or the metrics server.

    See the RKE documentation on private registries for more information on the private registry for components applied during the provisioning of the cluster.

    Authorized Cluster Endpoint​

    Authorized Cluster Endpoint can be used to directly access the Kubernetes API server, without requiring communication through Rancher.

    The authorized cluster endpoint is available only in clusters that Rancher has provisioned using RKE. It is not available for clusters in hosted Kubernetes providers, such as Amazon's EKS. Additionally, the authorized cluster endpoint cannot be enabled for RKE clusters that are registered with Rancher; it is available only on Rancher-launched Kubernetes clusters.

    This is enabled by default in Rancher-launched Kubernetes clusters, using the IP of the node with the controlplane role and the default Kubernetes self signed certificates.

    For more detail on how an authorized cluster endpoint works and why it is used, refer to the architecture section.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Node Pools​

    For information on using the Rancher UI to set up node pools in an RKE cluster, refer to this page.

    Advanced Options​

    The following options are available when you create clusters in the Rancher UI. They are located under Advanced Options.

    NGINX Ingress​

    Option to enable or disable the NGINX ingress controller.

    Node Port Range​

    Option to change the range of ports that can be used for NodePort services. Default is 30000-32767.

    Metrics Server Monitoring​

    Option to enable or disable Metrics Server.

    Pod Security Policy Support​

    Option to enable and select a default Pod Security Policy. You must have an existing Pod Security Policy configured before you can use this option.

    Docker Version on Nodes​

    Option to require a supported Docker version installed on the cluster nodes that are added to the cluster, or to allow unsupported Docker versions installed on the cluster nodes.

    Docker Root Directory​

    If the nodes you are adding to the cluster have Docker configured with a non-default Docker Root Directory (default is /var/lib/docker), please specify the correct Docker Root Directory in this option.

    Recurring etcd Snapshots​

    Option to enable or disable recurring etcd snapshots.

    Agent Environment Variables​

    Available as of v2.5.6

    Option to set environment variables for rancher agents. The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables can be set using agent environment variables.

    Cluster Config File​

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration. The system_images option is not supported when creating a cluster with the Rancher UI or API.

    • To edit an RKE config file directly from the Rancher UI, click Edit as YAML.
    • To read from an existing RKE file, click Read from a file.

    image

    Config File Structure in Rancher v2.3.0+​

    RKE (Rancher Kubernetes Engine) is the tool that Rancher uses to provision Kubernetes clusters. Rancher's cluster config files used to have the same structure as RKE config files, but the structure changed so that in Rancher, RKE cluster config items are separated from non-RKE config items. Therefore, configuration for your cluster needs to be nested under the rancher_kubernetes_engine_config directive in the cluster config file. Cluster config files created with earlier versions of Rancher will need to be updated for this format. An example cluster config file is included below.

    Example Cluster Config File
    #
    # Cluster Config
    #
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config: # Your RKE template config goes here.
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false
    windows_prefered_cluster: false

    Default DNS provider​

    The table below indicates what DNS provider is deployed by default. See RKE documentation on DNS provider for more information how to configure a different DNS provider. CoreDNS can only be used on Kubernetes v1.12.0 and higher.

    Rancher versionKubernetes versionDefault DNS provider
    v2.2.5 and higherv1.14.0 and higherCoreDNS
    v2.2.5 and higherv1.13.x and lowerkube-dns
    v2.2.4 and loweranykube-dns

    Rancher specific parameters

    Besides the RKE config file options, there are also Rancher specific settings that can be configured in the Config File (YAML):

    docker_root_dir​

    See Docker Root Directory.

    enable_cluster_monitoring​

    Option to enable or disable Cluster Monitoring.

    enable_network_policy​

    Option to enable or disable Project Network Isolation.

    Before Rancher v2.5.8, project network isolation is only available if you are using the Canal network plugin for RKE.

    In v2.5.8+, project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.

    local_cluster_auth_endpoint​

    See Authorized Cluster Endpoint.

    Example:

    local_cluster_auth_endpoint:
      enabled: true
      fqdn: "FQDN"
      ca_certs: "BASE64_CACERT"

    Custom Network Plug-in​

    You can add a custom network plug-in by using the user-defined add-on functionality of RKE. You define any add-on that you want deployed after the Kubernetes cluster is deployed.

    There are two ways that you can specify an add-on:

    For an example of how to configure a custom network plug-in by editing the cluster.yml, refer to the RKE documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/contribute-to-rancher.html b/v2.5/contribute-to-rancher.html index f34b104fada..4bbfde66827 100644 --- a/v2.5/contribute-to-rancher.html +++ b/v2.5/contribute-to-rancher.html @@ -5,14 +5,14 @@ Contributing to Rancher | Rancher Manager - +
    Version: v2.5

    Contributing to Rancher

    This section explains the repositories used for Rancher, how to build the repositories, and what information to include when you file an issue.

    For more detailed information on how to contribute to the development of Rancher projects, refer to the Rancher Developer Wiki. The wiki has resources on many topics, including the following:

    • How to set up the Rancher development environment and run tests
    • The typical flow of an issue through the development lifecycle
    • Coding guidelines and development best practices
    • Debugging and troubleshooting
    • Developing the Rancher API

    On the Rancher Users Slack, the channel for developers is #developer.

    Repositories

    All of repositories are located within our main GitHub organization. There are many repositories used for Rancher, but we'll provide descriptions of some of the main ones used in Rancher.

    RepositoryURLDescription
    Rancherhttps://github.com/rancher/rancherThis repository is the main source code for Rancher 2.x.
    Typeshttps://github.com/rancher/typesThis repository is the repository that has all the API types for Rancher 2.x.
    API Frameworkhttps://github.com/rancher/normanThis repository is an API framework for building Rancher style APIs backed by Kubernetes Custom Resources.
    User Interfacehttps://github.com/rancher/uiThis repository is the source of the UI.
    (Rancher) Docker Machinehttps://github.com/rancher/machineThis repository is the source of the Docker Machine binary used when using Node Drivers. This is a fork of the docker/machine repository.
    machine-packagehttps://github.com/rancher/machine-packageThis repository is used to build the Rancher Docker Machine binary.
    kontainer-enginehttps://github.com/rancher/kontainer-engineThis repository is the source of kontainer-engine, the tool to provision hosted Kubernetes clusters.
    RKE repositoryhttps://github.com/rancher/rkeThis repository is the source of Rancher Kubernetes Engine, the tool to provision Kubernetes clusters on any machine.
    CLIhttps://github.com/rancher/cliThis repository is the source code for the Rancher CLI used in Rancher 2.x.
    (Rancher) Helm repositoryhttps://github.com/rancher/helmThis repository is the source of the packaged Helm binary. This is a fork of the helm/helm repository.
    Telemetry repositoryhttps://github.com/rancher/telemetryThis repository is the source for the Telemetry binary.
    loglevel repositoryhttps://github.com/rancher/loglevelThis repository is the source of the loglevel binary, used to dynamically change log levels.

    To see all libraries/projects used in Rancher, see the go.mod file in the rancher/rancher repository.

    Rancher diagram

    Rancher components used for provisioning/managing Kubernetes clusters.

    Building

    Every repository should have a Makefile and can be built using the make command. The make targets are based on the scripts in the /scripts directory in the repository, and each target will use Dapper to run the target in an isolated environment. The Dockerfile.dapper will be used for this process, and includes all the necessary build tooling needed.

    The default target is ci, and will run ./scripts/validate, ./scripts/build, ./scripts/test and ./scripts/package. The resulting binaries of the build will be in ./build/bin and are usually also packaged in a Docker image.

    Bugs, Issues or Questions

    If you find any bugs or are having any trouble, please search the reported issue as someone may have experienced the same issue or we are actively working on a solution.

    If you can't find anything related to your issue, contact us by filing an issue. Though we have many repositories related to Rancher, we want the bugs filed in the Rancher repository so we won't miss them! If you want to ask a question or ask fellow users about an use case, we suggest creating a post on the Rancher Forums.

    Checklist for Filing Issues​

    Please follow this checklist when filing an issue which will helps us investigate and fix the issue. More info means more data we can use to determine what is causing the issue or what might be related to the issue.

    Note: For large amounts of data, please use GitHub Gist or similar and link the created resource in the issue. Important: Please remove any sensitive data as it will be publicly viewable.

    • Resources: Provide as much as detail as possible on the used resources. As the source of the issue can be many things, including as much of detail as possible helps to determine the root cause. See some examples below:

      • Hosts: What specifications does the host have, like CPU/memory/disk, what cloud does it happen on, what Amazon Machine Image are you using, what DigitalOcean droplet are you using, what image are you provisioning that we can rebuild or use when we try to reproduce
      • Operating System: What operating system are you using? Providing specifics helps here like the output of cat /etc/os-release for exact OS release and uname -r for exact kernel used
      • Docker: What Docker version are you using, how did you install it? Most of the details of Docker can be found by supplying output of docker version and docker info
      • Environment: Are you in a proxy environment, are you using recognized CA/self signed certificates, are you using an external loadbalancer
      • Rancher: What version of Rancher are you using, this can be found on the bottom left of the UI or be retrieved from the image tag you are running on the host
      • Clusters: What kind of cluster did you create, how did you create it, what did you specify when you were creating it

    • Steps to reproduce the issue: Provide as much detail on how you got into the reported situation. This helps the person to reproduce the situation you are in.

      • Provide manual steps or automation scripts used to get from a newly created setup to the situation you reported.

    • Logs: Provide data/logs from the used resources.

      • Rancher

        • Docker install

          docker logs \
          --timestamps \
          $(docker ps | grep -E "rancher/rancher:|rancher/rancher " | awk '{ print $1 }')

        • Kubernetes install using kubectl

          Note: Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml if Rancher is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

          kubectl -n cattle-system \
          logs \
          -l app=rancher \
          --timestamps=true

        • Docker install using docker on each of the nodes in the RKE cluster

          docker logs \
          --timestamps \
          $(docker ps | grep -E "rancher/rancher@|rancher_rancher" | awk '{ print $1 }')

        • Kubernetes Install with RKE Add-On

          Note: Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml if the Rancher server is installed on a Kubernetes cluster) or are using the embedded kubectl via the UI.

          kubectl -n cattle-system \
          logs \
          --timestamps=true \
          -f $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name="cattle-server") | .metadata.name')

      • System logging (these might not all exist, depending on operating system)

        • /var/log/messages
        • /var/log/syslog
        • /var/log/kern.log

      • Docker daemon logging (these might not all exist, depending on operating system)

        • /var/log/docker.log

    • Metrics: If you are experiencing performance issues, please provide as much of data (files or screenshots) of metrics which can help determining what is going on. If you have an issue related to a machine, it helps to supply output of top, free -m, df which shows processes/memory/disk usage.

    Docs

    If you have any updates to our documentation, please make any pull request to our docs repo.

    • Rancher 2.x Docs repository: This repo is where all the docs for Rancher 2.x are located. They are located in the content folder in the repo.

    • Rancher 1.x Docs repository: This repo is where all the docs for Rancher 1.x are located. They are located in the rancher folder in the repo.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations.html b/v2.5/explanations.html index 9afe182d6e0..3ffa7a6b361 100644 --- a/v2.5/explanations.html +++ b/v2.5/explanations.html @@ -5,13 +5,13 @@ Explanations | Rancher Manager - +
    Version: v2.5

    Explanations

    Explanatory docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/cis-scans/configuration-reference.html b/v2.5/explanations/integrations-in-rancher/cis-scans/configuration-reference.html index 2d992fd7e5e..213ac4a9497 100644 --- a/v2.5/explanations/integrations-in-rancher/cis-scans/configuration-reference.html +++ b/v2.5/explanations/integrations-in-rancher/cis-scans/configuration-reference.html @@ -5,13 +5,13 @@ Configuration | Rancher Manager - +
    Version: v2.5

    Configuration

    This configuration reference is intended to help you manage the custom resources created by the rancher-cis-benchmark application. These resources are used for performing CIS scans on a cluster, skipping tests, setting the test profile that will be used during a scan, and other customization.

    To configure the custom resources, go to the Cluster Explorer in the Rancher UI. In dropdown menu in the top left corner, click Cluster Explorer > CIS Benchmark.

    Scans​

    A scan is created to trigger a CIS scan on the cluster based on the defined profile. A report is created after the scan is completed.

    When configuring a scan, you need to define the name of the scan profile that will be used with the scanProfileName directive.

    An example ClusterScan custom resource is below:

    apiVersion: cis.cattle.io/v1
    kind: ClusterScan
    metadata:
      name: rke-cis
    spec:
      scanProfileName: rke-profile-hardened

    Profiles​

    A profile contains the configuration for the CIS scan, which includes the benchmark version to use and any specific tests to skip in that benchmark.

    By default, a few ClusterScanProfiles are installed as part of the rancher-cis-benchmark chart. If a user edits these default benchmarks or profiles, the next chart update will reset them back. So it is advisable for users to not edit the default ClusterScanProfiles.

    Users can clone the ClusterScanProfiles to create custom profiles.

    Skipped tests are listed under the skipTests directive.

    When you create a new profile, you will also need to give it a name.

    An example ClusterScanProfile is below:

    apiVersion: cis.cattle.io/v1
    kind: ClusterScanProfile
    metadata:
      annotations:
        meta.helm.sh/release-name: clusterscan-operator
        meta.helm.sh/release-namespace: cis-operator-system
      labels:
        app.kubernetes.io/managed-by: Helm
      name: "<example-profile>"
    spec:
      benchmarkVersion: cis-1.5
      skipTests:
        - "1.1.20"
        - "1.1.21"

    Benchmark Versions​

    A benchmark version is the name of benchmark to run using kube-bench, as well as the valid configuration parameters for that benchmark.

    A ClusterScanBenchmark defines the CIS BenchmarkVersion name and test configurations. The BenchmarkVersion name is a parameter provided to the kube-bench tool.

    By default, a few BenchmarkVersion names and test configurations are packaged as part of the CIS scan application. When this feature is enabled, these default BenchmarkVersions will be automatically installed and available for users to create a ClusterScanProfile.

    If the default BenchmarkVersions are edited, the next chart update will reset them back. Therefore we don't recommend editing the default ClusterScanBenchmarks.

    A ClusterScanBenchmark consists of the fields:

    • ClusterProvider: This is the cluster provider name for which this benchmark is applicable. For example: RKE, EKS, GKE, etc. Leave it empty if this benchmark can be run on any cluster type.
    • MinKubernetesVersion: Specifies the cluster's minimum kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular Kubernetes version.
    • MaxKubernetesVersion: Specifies the cluster's maximum Kubernetes version necessary to run this benchmark. Leave it empty if there is no dependency on a particular k8s version.

    An example ClusterScanBenchmark is below:

    apiVersion: cis.cattle.io/v1
    kind: ClusterScanBenchmark
    metadata:
      annotations:
        meta.helm.sh/release-name: clusterscan-operator
        meta.helm.sh/release-namespace: cis-operator-system
      creationTimestamp: "2020-08-28T18:18:07Z"
      generation: 1
      labels:
        app.kubernetes.io/managed-by: Helm
      name: cis-1.5
      resourceVersion: "203878"
      selfLink: /apis/cis.cattle.io/v1/clusterscanbenchmarks/cis-1.5
      uid: 309e543e-9102-4091-be91-08d7af7fb7a7
    spec:
      clusterProvider: ""
      minKubernetesVersion: 1.15.0
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html b/v2.5/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html index 4541dddca1c..69734352c0f 100644 --- a/v2.5/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html +++ b/v2.5/explanations/integrations-in-rancher/cis-scans/custom-benchmark.html @@ -5,14 +5,14 @@ Creating a Custom Benchmark Version for Running a Cluster Scan | Rancher Manager - +
    Version: v2.5

    Creating a Custom Benchmark Version for Running a Cluster Scan

    Available as of v2.5.4

    Each Benchmark Version defines a set of test configuration files that define the CIS tests to be run by the kube-bench tool. The rancher-cis-benchmark application installs a few default Benchmark Versions which are listed under CIS Benchmark application menu.

    But there could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.

    It is now possible to create a custom Benchmark Version for running a cluster scan using the rancher-cis-benchmark application.

    When a cluster scan is run, you need to select a Profile which points to a specific Benchmark Version.

    Follow all the steps below to add a custom Benchmark Version and run a scan using it.

    1. Prepare the Custom Benchmark Version ConfigMap​

    To create a custom benchmark version, first you need to create a ConfigMap containing the benchmark version's config files and upload it to your Kubernetes cluster where you want to run the scan.

    To prepare a custom benchmark version ConfigMap, suppose we want to add a custom Benchmark Version named foo.

    1. Create a directory named foo and inside this directory, place all the config YAML files that the kube-bench tool looks for. For example, here are the config YAML files for a Generic CIS 1.5 Benchmark Version https://github.com/aquasecurity/kube-bench/tree/master/cfg/cis-1.5

    2. Place the complete config.yaml file, which includes all the components that should be tested.

    3. Add the Benchmark version name to the target_mapping section of the config.yaml:

      target_mapping:
        "foo":
          - "master"
          - "node"
          - "controlplane"
          - "etcd"
          - "policies"

    4. Upload this directory to your Kubernetes Cluster by creating a ConfigMap:

      kubectl create configmap -n <namespace> foo --from-file=<path to directory foo>

    2. Add a Custom Benchmark Version to a Cluster​

    1. Once the ConfigMap has been created in your cluster, navigate to the Cluster Explorer in the Rancher UI.
    2. In the top left dropdown menu, click Cluster Explorer > CIS Benchmark.
    3. In the Benchmark Versions section, click Create.
    4. Enter the Name and a description for your custom benchmark version.
    5. Choose the cluster provider that your benchmark version applies to.
    6. Choose the ConfigMap you have uploaded from the dropdown.
    7. Add the minimum and maximum Kubernetes version limits applicable, if any.
    8. Click Create.

    3. Create a New Profile for the Custom Benchmark Version​

    To run a scan using your custom benchmark version, you need to add a new Profile pointing to this benchmark version.

    1. Once the custom benchmark version has been created in your cluster, navigate to the Cluster Explorer in the Rancher UI.
    2. In the top left dropdown menu, click Cluster Explorer > CIS Benchmark.
    3. In the Profiles section, click Create.
    4. Provide a Name and description. In this example, we name it foo-profile.
    5. Choose the Benchmark Version foo from the dropdown.
    6. Click Create.

    4. Run a Scan Using the Custom Benchmark Version​

    Once the Profile pointing to your custom benchmark version foo has been created, you can create a new Scan to run the custom test configs in the Benchmark Version.

    To run a scan,

    1. Go to the Cluster Explorer in the Rancher UI. In the top left dropdown menu, click Cluster Explorer > CIS Benchmark.
    2. In the Scans section, click Create.
    3. Choose the new cluster scan profile foo-profile.
    4. Click Create.

    Result: A report is generated with the scan results. To see the results, click the name of the scan that appears.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html b/v2.5/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html index d157e605f57..a1677ddc912 100644 --- a/v2.5/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html +++ b/v2.5/explanations/integrations-in-rancher/cis-scans/rbac-for-cis-scans.html @@ -5,7 +5,7 @@ Roles-based Access Control | Rancher Manager - + @@ -15,7 +15,7 @@ Rancher v2.5.2 because it essentially is same as cis-admin. If you for cis-edit, please update them to use cis-admin ClusterRole instead.

    Cluster-Admin Access​

    Rancher CIS Scans is a cluster-admin only feature by default. This means only the Rancher global admins, and the cluster’s cluster-owner can:

    • Install/Uninstall the rancher-cis-benchmark App
    • See the navigation links for CIS Benchmark CRDs - ClusterScanBenchmarks, ClusterScanProfiles, ClusterScans
    • List the default ClusterScanBenchmarks and ClusterScanProfiles
    • Create/Edit/Delete new ClusterScanProfiles
    • Create/Edit/Delete a new ClusterScan to run the CIS scan on the cluster
    • View and Download the ClusterScanReport created after the ClusterScan is complete

    Summary of Default Permissions for Kubernetes Default Roles​

    The rancher-cis-benchmark creates three ClusterRoles and adds the CIS Benchmark CRD access to the following default K8s ClusterRoles:

    ClusterRole created by chartDefault K8s ClusterRolePermissions given with Role
    cis-adminadminAbility to CRUD clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR
    cis-viewview Ability to List(R) clusterscanbenchmarks, clusterscanprofiles, clusterscans, clusterscanreports CR

    By default only cluster-owner role will have ability to manage and use rancher-cis-benchmark feature.

    The other Rancher roles (cluster-member, project-owner, project-member) do not have any default permissions to manage and use rancher-cis-benchmark resources.

    But if a cluster-owner wants to delegate access to other users, they can do so by creating ClusterRoleBindings between these users and the above CIS ClusterRoles manually. There is no automatic role aggregation supported for the rancher-cis-benchmark ClusterRoles.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html b/v2.5/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html index 5cd572aa43a..b75ee46acc9 100644 --- a/v2.5/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html +++ b/v2.5/explanations/integrations-in-rancher/cis-scans/skipped-and-not-applicable-tests.html @@ -5,13 +5,13 @@ Skipped and Not Applicable Tests | Rancher Manager - +
    Version: v2.5

    Skipped and Not Applicable Tests

    This section lists the tests that are skipped in the permissive test profile for RKE.

    All the tests that are skipped and not applicable on this page will be counted as Not Applicable in the v2.5 generated report. The skipped test count will only mention the user-defined skipped tests. This allows user-skipped tests to be distinguished from the tests that are skipped by default in the RKE permissive test profile.

    CIS Benchmark v1.5​

    CIS Benchmark v1.5 Skipped Tests​

    NumberDescriptionReason for Skipping
    1.1.12Ensure that the etcd data directory ownership is set to etcd:etcd (Automated)A system service account is required for etcd data directory ownership. Refer to Rancher's hardening guide for more details on how to configure this ownership.
    1.2.6Ensure that the --kubelet-certificate-authority argument is set as appropriate (Automated)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
    1.2.16Ensure that the admission control plugin PodSecurityPolicy is set (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    1.2.33Ensure that the --encryption-provider-config argument is set as appropriate (Manual)Enabling encryption changes how data can be recovered as data is encrypted.
    1.2.34Ensure that encryption providers are appropriately configured (Manual)Enabling encryption changes how data can be recovered as data is encrypted.
    4.2.6Ensure that the --protect-kernel-defaults argument is set to true (Automated)System level configurations are required before provisioning the cluster in order for this argument to be set to true.
    4.2.10Ensure that the--tls-cert-file and --tls-private-key-file arguments are set as appropriate (Automated)When generating serving certificates, functionality could break in conjunction with hostname overrides which are required for certain cloud providers.
    5.1.5Ensure that default service accounts are not actively used. (Automated)Kubernetes provides default service accounts to be used.
    5.2.2Minimize the admission of containers wishing to share the host process ID namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.3Minimize the admission of containers wishing to share the host IPC namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.4Minimize the admission of containers wishing to share the host network namespace (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.2.5Minimize the admission of containers with allowPrivilegeEscalation (Automated)Enabling Pod Security Policy can cause applications to unexpectedly fail.
    5.3.2Ensure that all Namespaces have Network Policies defined (Automated)Enabling Network Policies can prevent certain applications from communicating with each other.
    5.6.4The default namespace should not be used (Automated)Kubernetes provides a default namespace.

    CIS Benchmark v1.5 Not Applicable Tests​

    NumberDescriptionReason for being not applicable
    1.1.1Ensure that the API server pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
    1.1.2Ensure that the API server pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for kube-apiserver. All configuration is passed in as arguments at container run time.
    1.1.3Ensure that the controller manager pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.4Ensure that the controller manager pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.5Ensure that the scheduler pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.6Ensure that the scheduler pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.7Ensure that the etcd pod specification file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
    1.1.8Ensure that the etcd pod specification file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for etcd. All configuration is passed in as arguments at container run time.
    1.1.13Ensure that the admin.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    1.1.14Ensure that the admin.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE does not store the kubernetes default kubeconfig credentials file on the nodes.
    1.1.15Ensure that the scheduler.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.16Ensure that the scheduler.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for scheduler. All configuration is passed in as arguments at container run time.
    1.1.17Ensure that the controller-manager.conf file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.1.18Ensure that the controller-manager.conf file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn't require or maintain a configuration file for controller-manager. All configuration is passed in as arguments at container run time.
    1.3.6Ensure that the RotateKubeletServerCertificate argument is set to true (Automated)Clusters provisioned by RKE handles certificate rotation directly through RKE.
    4.1.1Ensure that the kubelet service file permissions are set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
    4.1.2Ensure that the kubelet service file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet service. All configuration is passed in as arguments at container run time.
    4.1.9Ensure that the kubelet configuration file has permissions set to 644 or more restrictive (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
    4.1.10Ensure that the kubelet configuration file ownership is set to root:root (Automated)Clusters provisioned by RKE doesn’t require or maintain a configuration file for the kubelet. All configuration is passed in as arguments at container run time.
    4.2.12Ensure that the RotateKubeletServerCertificate argument is set to true (Automated)Clusters provisioned by RKE handles certificate rotation directly through RKE.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html index 66d4f5c2307..2385ecda672 100644 --- a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html +++ b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
    Version: v2.5

    Architecture

    Fleet can manage deployments from git of raw Kubernetes YAML, Helm charts, or Kustomize or any combination of the three. Regardless of the source, all resources are dynamically turned into Helm charts, and Helm is used as the engine to deploy everything in the cluster. This gives you a high degree of control, consistency, and auditability. Fleet focuses not only on the ability to scale, but to give one a high degree of control and visibility to exactly what is installed on the cluster.

    Architecture

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html index a096f6b628b..4edcf5af610 100644 --- a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html +++ b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.html @@ -5,13 +5,13 @@ Using Fleet Behind a Proxy | Rancher Manager - +
    Version: v2.5

    Using Fleet Behind a Proxy

    Available as of v2.5.8

    In this section, you'll learn how to enable Fleet in a setup that has a Rancher server with a public IP a Kubernetes cluster that has no public IP, but is configured to use a proxy.

    Rancher does not establish connections with registered downstream clusters. The Rancher agent deployed on the downstream cluster must be able to establish the connection with Rancher.

    To set up Fleet to work behind a proxy, you will need to set the Agent Environment Variables for the downstream cluster. These are cluster-level configuration options.

    Through the Rancher UI, you can configure these environment variables for any cluster type, including registered and custom clusters. The variables can be added while editing an existing cluster or while provisioning a new cluster.

    For public downstream clusters, it is sufficient to set the required environment variables in the Rancher UI.

    For private nodes or private clusters, the environment variables need to be set on the nodes themselves. Then the environment variables are configured from the Rancher UI, typically when provisioning a custom cluster or when registering the private cluster. For an example of how to set the environment variables on Ubuntu node in a K3s Kubernetes cluster, see this section.

    Required Environment Variables​

    When adding Fleet agent environment variables for the proxy, replace <PROXY_IP> with your private proxy IP.

    Variable NameValue
    HTTP_PROXYhttp://<PROXY_IP>:8888
    HTTPS_PROXYhttp://<PROXY_IP>:8888
    NO_PROXY127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local

    Setting Environment Variables in the Rancher UI​

    To add the environment variable to an existing cluster,

    1. In the Rancher UI, go to the cluster view for Kubernetes cluster that needs to use a proxy.
    2. Click ⋮ > Edit.
    3. Click Advanced Options.
    4. Click Add Environment Variable.
    5. Enter the required environment variables
    6. Click Save.

    Result: The Fleet agent works behind a proxy.

    Setting Environment Variables on Private Nodes​

    For private nodes and private clusters, the proxy environment variables need to be set on the nodes themselves, as well as configured from the Rancher UI.

    This example shows how the environment variables would be set up on an Ubuntu node in a K3s Kubernetes cluster:

    ssh -o ForwardAgent=yes ubuntu@<public_proxy_ip>
    ssh <k3s_ip>
    export proxy_private_ip=<private_proxy_ip>
    export HTTP_PROXY=http://${proxy_private_ip}:8888
    export HTTPS_PROXY=http://${proxy_private_ip}:8888
    export NO_PROXY=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local
    export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html index 57c5510b3f0..edd20d47c07 100644 --- a/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html +++ b/v2.5/explanations/integrations-in-rancher/fleet-gitops-at-scale/windows-support.html @@ -5,13 +5,13 @@ Windows Support | Rancher Manager - +
    Version: v2.5

    Windows Support

    Prior to Rancher v2.5.6, the agent did not have native Windows manifests on downstream clusters with Windows nodes. This would result in a failing agent pod for the cluster.

    If you are upgrading from an older version of Rancher to v2.5.6+, you can deploy a working agent with the following workflow in the downstream cluster:

    1. Cordon all Windows nodes.
    2. Apply the below toleration to the agent workload.
    3. Uncordon all Windows nodes.
    4. Delete all agent pods. New pods should be created with the new toleration.
    5. Once the agent pods are running, and auto-update is enabled for Fleet, they should be updated to a Windows-compatible agent version.
    tolerations:
    - effect: NoSchedule
      key: cattle.io/os
      operator: Equal
      value: linux
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html index 4ddd2036b7d..96e26cd4e8b 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html +++ b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.html @@ -5,13 +5,13 @@ Additional Steps for Installing Istio on an RKE2 Cluster | Rancher Manager - +
    Version: v2.5

    Additional Steps for Installing Istio on an RKE2 Cluster

    Through the Cluster Explorer, when installing or upgrading Istio through Apps & Marketplace,

    1. Click Components.

    2. Check the box next to Enabled CNI.

    3. Add a custom overlay file specifying cniBinDir and cniConfDir. For more information on these options, refer to the Istio documentation. An example is below:

      apiVersion: install.istio.io/v1alpha1
      kind: IstioOperator
      spec:
        components:
          cni:
            enabled: true
        values:
          cni:
            image: rancher/istio-install-cni:1.7.3
            excludeNamespaces:
              - istio-system
              - kube-system
            logLevel: info
            cniBinDir: /opt/cni/bin
            cniConfDir: /etc/cni/net.d

    4. After installing Istio, you'll notice the cni-node pods in the istio-system namespace in a CrashLoopBackoff error. Manually edit the istio-cni-node daemonset to include the following on the install-cni container:

      securityContext:
          privileged: true

    Result: Now you should be able to utilize Istio as desired, including sidecar injection and monitoring via Kiali.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html index 5d1d1b9d330..3a4f76a7b58 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html +++ b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/pod-security-policies.html @@ -5,13 +5,13 @@ Enable Istio with Pod Security Policies | Rancher Manager - +
    Version: v2.5

    Enable Istio with Pod Security Policies

    If you have restrictive Pod Security Policies enabled, then Istio may not be able to function correctly, because it needs certain permissions in order to install itself and manage pod infrastructure. In this section, we will configure a cluster with PSPs enabled for an Istio install, and also set up the Istio CNI plugin.

    The Istio CNI plugin removes the need for each application pod to have a privileged NET_ADMIN container. For further information, see the Istio CNI Plugin docs. Please note that the Istio CNI Plugin is in alpha.

    The steps differ based on the Rancher version.

    Prerequisites:

    • The cluster must be an RKE Kubernetes cluster.
    • The cluster must have been created with a default PodSecurityPolicy.

    To enable pod security policy support when creating a Kubernetes cluster in the Rancher UI, go to Advanced Options. In the Pod Security Policy Support section, click Enabled. Then select a default pod security policy.

    1. Set the PodSecurityPolicy to unrestricted
    2. Enable the CNI
    3. Verify that the CNI is working.

    1. Set the PodSecurityPolicy to unrestricted​

    An unrestricted PSP allows Istio to be installed.

    Set the PSP to unrestricted in the project where is Istio is installed, or the project where you plan to install Istio.

    1. From the cluster view of the Cluster Manager, select Projects/Namespaces.
    2. Find the Project: System and select the ⋮ > Edit.
    3. Change the Pod Security Policy option to be unrestricted, then click Save.

    2. Enable the CNI​

    When installing or upgrading Istio through Apps & Marketplace,

    1. Click Components.
    2. Check the box next to Enabled CNI.
    3. Finish installing or upgrading Istio.

    The CNI can also be enabled by editing the values.yaml:

    istio_cni.enabled: true

    Istio should install successfully with the CNI enabled in the cluster.

    3. Verify that the CNI is working​

    Verify that the CNI is working by deploying a sample application or deploying one of your own applications.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html index 7f1d1002180..8fb3fde7810 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html +++ b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/project-network-isolation.html @@ -5,13 +5,13 @@ Additional Steps for Project Network Isolation | Rancher Manager - +
    Version: v2.5

    Additional Steps for Project Network Isolation

    In clusters where:

    • You are using the Canal network plugin with Rancher before v2.5.8, or you are using Rancher v2.5.8+ with an any RKE network plug-in that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin
    • The Project Network Isolation option is enabled
    • You install the Istio Ingress module

    The Istio Ingress Gateway pod won't be able to redirect ingress traffic to the workloads by default. This is because all the namespaces will be inaccessible from the namespace where Istio is installed. You have two options.

    The first option is to add a new Network Policy in each of the namespaces where you intend to have ingress controlled by Istio. Your policy should include the following lines:

    - podSelector:
        matchLabels:
          app: istio-ingressgateway

    The second option is to move the istio-system namespace to the system project, which by default is excluded from the network isolation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html index a314d11e0cb..ed757215118 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html +++ b/v2.5/explanations/integrations-in-rancher/istio/configuration-options/selectors-and-scrape-configurations.html @@ -5,13 +5,13 @@ Selectors and Scrape Configs | Rancher Manager - +
    Version: v2.5

    Selectors and Scrape Configs

    The Monitoring app sets prometheus.prometheusSpec.ignoreNamespaceSelectors=false, which enables monitoring across all namespaces by default.

    This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with istio-injection=enabled label.

    If you would like to limit Prometheus to specific namespaces, set prometheus.prometheusSpec.ignoreNamespaceSelectors=true. Once you do this, you will need to add additional configuration to continue to monitor your resources.

    Limiting Monitoring to Specific Namespaces by Setting ignoreNamespaceSelectors to True​

    This limits monitoring to specific namespaces.

    1. From the Cluster Explorer, navigate to Installed Apps if Monitoring is already installed, or Charts in Apps & Marketplace
    2. If starting a new install, Click the rancher-monitoring chart, then in Chart Options click Edit as Yaml.
    3. If updating an existing installation, click on Upgrade, then in Chart Options click Edit as Yaml.
    4. Setprometheus.prometheusSpec.ignoreNamespaceSelectors=true
    5. Complete install or upgrade

    Result: Prometheus will be limited to specific namespaces which means one of the following configurations will need to be set up to continue to view data in various dashboards

    Enabling Prometheus to Detect Resources in Other Namespaces​

    There are two different ways to enable Prometheus to detect resources in other namespaces when prometheus.prometheusSpec.ignoreNamespaceSelectors=true:

    • Monitoring specific namespaces: Add a Service Monitor or Pod Monitor in the namespace with the targets you want to scrape.
    • Monitoring across namespaces: Add an additionalScrapeConfig to your rancher-monitoring instance to scrape all targets in all namespaces.

    Monitoring Specific Namespaces: Create a Service Monitor or Pod Monitor​

    This option allows you to define which specific services or pods you would like monitored in a specific namespace.

    The usability tradeoff is that you have to create the service monitor or pod monitor per namespace since you cannot monitor across namespaces.

    Prerequisite: Define a ServiceMonitor or PodMonitor for <your namespace>. An example ServiceMonitor is provided below.

    1. From the Cluster Explorer, open the kubectl shell
    2. Run kubectl create -f <name of service/pod monitor file>.yaml if the file is stored locally in your cluster.
    3. Or run cat<< EOF | kubectl apply -f -, paste the file contents into the terminal, then run EOF to complete the command.
    4. If starting a new install, Click the rancher-monitoring chart and scroll down to Preview Yaml.
    5. Run kubectl label namespace <your namespace> istio-injection=enabled to enable the envoy sidecar injection

    Result: <your namespace> can be scraped by prometheus.

    Example Service Monitor for Istio Proxies
    apiVersion: monitoring.coreos.com/v1
    kind: ServiceMonitor
    metadata:
      name: envoy-stats-monitor
      namespace: istio-system
      labels:
        monitoring: istio-proxies
    spec:
      selector:
        matchExpressions:
        - {key: istio-prometheus-ignore, operator: DoesNotExist}
      namespaceSelector:
        any: true
      jobLabel: envoy-stats
      endpoints:
      - path: /stats/prometheus
        targetPort: 15090
        interval: 15s
        relabelings:
        - sourceLabels: [__meta_kubernetes_pod_container_port_name]
          action: keep
          regex: '.*-envoy-prom'
        - action: labeldrop
          regex: "__meta_kubernetes_pod_label_(.+)"
        - sourceLabels: [__meta_kubernetes_namespace]
          action: replace
          targetLabel: namespace
        - sourceLabels: [__meta_kubernetes_pod_name]
          action: replace
          targetLabel: pod_name

    Monitoring across namespaces: Set ignoreNamespaceSelectors to False​

    This enables monitoring across namespaces by giving Prometheus additional scrape configurations.

    The usability tradeoff is that all of Prometheus' additionalScrapeConfigs are maintained in a single Secret. This could make upgrading difficult if monitoring is already deployed with additionalScrapeConfigs before installing Istio.

    1. If starting a new install, Click the rancher-monitoring chart, then in Chart Options click Edit as Yaml.
    2. If updating an existing installation, click on Upgrade, then in Chart Options click Edit as Yaml.
    3. If updating an existing installation, click on Upgrade and then Preview Yaml.
    4. Setprometheus.prometheusSpec.additionalScrapeConfigs array to the Additional Scrape Config provided below.
    5. Complete install or upgrade

    Result: All namespaces with the istio-injection=enabled label will be scraped by prometheus.

    Additional Scrape Config
    - job_name: 'istio/envoy-stats'
      scrape_interval: 15s
      metrics_path: /stats/prometheus
      kubernetes_sd_configs:
        - role: pod
      relabel_configs:
        - source_labels: [__meta_kubernetes_pod_container_port_name]
          action: keep
          regex: '.*-envoy-prom'
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: ([^:]+)(?::\d+)?;(\d+)
          replacement: $1:15090
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)
        - source_labels: [__meta_kubernetes_namespace]
          action: replace
          target_label: namespace
        - source_labels: [__meta_kubernetes_pod_name]
          action: replace
          target_label: pod_name
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html b/v2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html index 819aa8f546c..8cd083ef354 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html +++ b/v2.5/explanations/integrations-in-rancher/istio/cpu-and-memory-allocations.html @@ -5,13 +5,13 @@ CPU and Memory Allocations | Rancher Manager - +
    Version: v2.5

    CPU and Memory Allocations

    This section describes the minimum recommended computing resources for the Istio components in a cluster.

    The CPU and memory allocations for each component are configurable.

    Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

    Tip: In larger deployments, it is strongly advised that the infrastructure be placed on dedicated nodes in the cluster by adding a node selector for each Istio component.

    The table below shows a summary of the minimum recommended resource requests and limits for the CPU and memory of each core Istio component.

    In Kubernetes, the resource request indicates that the workload will not be deployed on a node unless the node has at least the specified amount of memory and CPU available. If the workload surpasses the limit for CPU or memory, it can be terminated or evicted from the node. For more information on managing resource limits for containers, refer to the Kubernetes documentation.

    WorkloadCPU - RequestMemory - RequestCPU - LimitMemory - Limit
    ingress gateway100m128mi2000m1024mi
    egress gateway100m128mi2000m1024mi
    istiod500m2048miNo limitNo limit
    proxy10m10mi2000m1024mi
    Totals:710m2314Mi6000m3072Mi

    Configuring Resource Allocations

    You can individually configure the resource allocation for each type of Istio component. This section includes the default resource allocations for each component.

    To make it easier to schedule the workloads to a node, a cluster-admin can reduce the CPU and memory resource requests for the component. However, the default CPU and memory allocations are the minimum that we recommend.

    You can find more information about Istio configuration in the official Istio documentation.

    To configure the resources allocated to an Istio component,

    1. In the Rancher Cluster Explorer, navigate to your Istio installation in Apps & Marketplace
    2. Click Upgrade to edit the base components via changes to the values.yaml or add an overlay file. For more information about editing the overlay file, see this section.
    3. Change the CPU or memory allocations, the nodes where each component will be scheduled to, or the node tolerations.
    4. Click Upgrade. to rollout changes

    Result: The resource allocations for the Istio components are updated.

    Editing the Overlay File​

    The overlay file can contain any of the values in the Istio Operator spec. The overlay file included with the Istio application is just one example of a potential configuration of the overlay file.

    As long as the file contains kind: IstioOperator and the YAML options are valid, the file can be used as an overlay.

    In the example overlay file provided with the Istio application, the following section allows you to change Kubernetes resources:

    #      k8s:
    #        resources:
    #          requests:
    #            cpu: 200m
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/disable-istio.html b/v2.5/explanations/integrations-in-rancher/istio/disable-istio.html index d4999adc950..5d9b248fe5d 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/disable-istio.html +++ b/v2.5/explanations/integrations-in-rancher/istio/disable-istio.html @@ -5,13 +5,13 @@ Disabling Istio | Rancher Manager - +
    Version: v2.5

    Disabling Istio

    This section describes how to uninstall Istio in a cluster or disable a namespace, or workload.

    Uninstall Istio in a Cluster​

    To uninstall Istio,

    1. From the Cluster Explorer, navigate to Installed Apps in Apps & Marketplace and locate the rancher-istio installation.
    2. Select rancher-istio in the `istio-system namespace and click Delete
    3. After rancher-istio is deleted, you can then select all the remaining apps in the istio-system namespace and click Delete

    Result: The rancher-istio app in the cluster gets removed. The Istio sidecar cannot be deployed on any workloads in the cluster.

    Note: You can no longer disable and re-enable your Istio installation. If you would like to save your settings for a future install, view and save individual YAMLs to refer back to / reuse for future installations.

    Troubleshooting Uninstall: If you didn't follow the uninstall steps, you may encounter a warning during uninstall:

    Error: uninstallation completed with 1 error(s): unable to build kubernetes objects for delete: unable to recognize "": no matches for kind "MonitoringDashboard" in version "monitoring.kiali.io/v1alpha1"

    This could mean a few things. You either selected all the apps in the istio-system namespace and deleted them at the same time, or you deleted rancher-istio chart dependencies prior to deleting the rancher-istio chart. Since the uninstall did not complete properly, you will have resources remaining in the istio-system namespace that you will need to manually clean up. Another option to avoid manual clean up is to install rancher-istio again, then uninstall it in the correct order.

    Disable Istio in a Namespace​

    1. From the Cluster Explorer view, use the side-nav to select Namespaces page
    2. On the Namespace page, you will see a list of namespaces. Go to the namespace where you want to disable and click the select Edit as Form or Edit as Yaml
    3. Remove the istio-injection=enabled label from the namespace
    4. Click Save

    Result: When workloads are deployed in this namespace, they will not have the Istio sidecar.

    Remove the Istio Sidecar from a Workload​

    Disable Istio in the namespace, then redeploy the workloads with in it. They will be deployed without the Istio sidecar.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/istio/rbac-for-istio.html b/v2.5/explanations/integrations-in-rancher/istio/rbac-for-istio.html index ff72c13e264..8956c034bd9 100644 --- a/v2.5/explanations/integrations-in-rancher/istio/rbac-for-istio.html +++ b/v2.5/explanations/integrations-in-rancher/istio/rbac-for-istio.html @@ -5,13 +5,13 @@ Role-based Access Control | Rancher Manager - +
    Version: v2.5

    Role-based Access Control

    This section describes the permissions required to access Istio features.

    The rancher istio chart installs three ClusterRoles

    Cluster-Admin Access​

    By default, only those with the cluster-admin ClusterRole can:

    • Install istio app in a cluster
    • Configure resource allocations for Istio

    Admin and Edit access​

    By default, only Admin and Edit roles can:

    • Enable and disable Istio sidecar auto-injection for namespaces
    • Add the Istio sidecar to workloads
    • View the traffic metrics and traffic graph for the cluster
    • Configure Istio's resources (such as the gateway, destination rules, or virtual services)

    Summary of Default Permissions for Kubernetes Default roles​

    Istio creates three ClusterRoles and adds Istio CRD access to the following default K8s ClusterRole:

    ClusterRole create by chartDefault K8s ClusterRoleRancher Role
    istio-adminadminProject Owner
    istio-editeditProject Member
    istio-viewviewRead-only

    Rancher will continue to use cluster-owner, cluster-member, project-owner, project-member, etc as role names, but will utilize default roles to determine access. For each default K8s ClusterRole there are different Istio CRD permissions and K8s actions (Create ( C ), Get ( G ), List ( L ), Watch ( W ), Update ( U ), Patch ( P ), Delete( D ), All ( * )) that can be performed.

    CRDsAdminEditView
    • config.istio.io
      • adapters
      • attributemanifests
      • handlers
      • httpapispecbindings
      • httpapispecs
      • instances
      • quotaspecbindings
      • quotaspecs
      • rules
      • templates
    		GLWGLWGLW
    • networking.istio.io
      • destinationrules
      • envoyfilters
      • gateways
      • serviceentries
      • sidecars
      • virtualservices
      • workloadentries
    		**GLW
    • security.istio.io
      • authorizationpolicies
      • peerauthentications
      • requestauthentications
    		**GLW
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html b/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html index 591b33e03b6..dd0fe715e29 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html +++ b/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/flows-and-clusterflows.html @@ -5,13 +5,13 @@ Flows and ClusterFlows | Rancher Manager - +
    Version: v2.5

    Flows and ClusterFlows

    For the full details on configuring Flows and ClusterFlows, see the Banzai Cloud Logging operator documentation.

    Configuration​

    Changes in v2.5.8​

    The Flows and ClusterFlows can now be configured by filling out forms in the Rancher UI.

    Flows​

    A Flow defines which logs to collect and filter and which output to send the logs to.

    The Flow is a namespaced resource, which means logs will only be collected from the namespace that the Flow is deployed in.

    For more details about the Flow custom resource, see FlowSpec.

    Matches​

    Match statements are used to select which containers to pull logs from.

    You can specify match statements to select or exclude logs according to Kubernetes labels, container and host names. Match statements are evaluated in the order they are defined and processed only until the first matching select or exclude rule applies.

    Matches can be configured by filling out the Flow or ClusterFlow forms in the Rancher UI.

    For detailed examples on using the match statement, see the official documentation on log routing.

    Filters​

    You can define one or more filters within a Flow. Filters can perform various actions on the logs, for example, add additional data, transform the logs, or parse values from the records. The filters in the Flow are applied in the order in the definition.

    For a list of filters supported by the Banzai Cloud Logging operator, see this page.

    Filters need to be configured in YAML.

    Outputs​

    This Output will receive logs from the Flow. Because the Flow is a namespaced resource, the Output must reside in same namespace as the Flow.

    Outputs can be referenced when filling out the Flow or ClusterFlow forms in the Rancher UI.

    ClusterFlows​

    Matches, filters and Outputs are configured for ClusterFlows in the same way that they are configured for Flows. The key difference is that the ClusterFlow is scoped at the cluster level and can configure log collection across all namespaces.

    After ClusterFlow selects logs from all namespaces in the cluster, logs from the cluster will be collected and logged to the selected ClusterOutput.

    YAML Example​

    The following example Flow transforms the log messages from the default namespace and sends them to an S3 Output:

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: Flow
    metadata:
      name: flow-sample
      namespace: default
    spec:
      filters:
        - parser:
            remove_key_name_field: true
            parse:
              type: nginx
        - tag_normaliser:
            format: ${namespace_name}.${pod_name}.${container_name}
      localOutputRefs:
        - s3-output
      match:
        - select:
            labels:
              app: nginx
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html b/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html index bce5ed65150..7cb069f0008 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html +++ b/v2.5/explanations/integrations-in-rancher/logging/custom-resource-configuration/outputs-and-clusteroutputs.html @@ -5,13 +5,13 @@ Outputs and ClusterOutputs | Rancher Manager - +
    Version: v2.5

    Outputs and ClusterOutputs

    For the full details on configuring Outputs and ClusterOutputs, see the Banzai Cloud Logging operator documentation.

    Configuration​

    Changes in v2.5.8​

    The Outputs and ClusterOutputs can now be configured by filling out forms in the Rancher UI.

    # Outputs

    The Output resource defines where your Flows can send the log messages. Outputs are the final stage for a logging Flow.

    The Output is a namespaced resource, which means only a Flow within the same namespace can access it.

    You can use secrets in these definitions, but they must also be in the same namespace.

    For the details of Output custom resource, see OutputSpec.

    The Rancher UI provides forms for configuring the following Output types:

    • Amazon ElasticSearch
    • Azure Storage
    • Cloudwatch
    • Datadog
    • Elasticsearch
    • File
    • Fluentd
    • GCS
    • Kafka
    • Kinesis Stream
    • LogDNA
    • LogZ
    • Loki
    • New Relic
    • Splunk
    • SumoLogic
    • Syslog

    The Rancher UI provides forms for configuring the Output type, target, and access credentials if applicable.

    For example configuration for each logging plugin supported by the logging operator, see the logging operator documentation.

    ClusterOutputs​

    ClusterOutput defines an Output without namespace restrictions. It is only effective when deployed in the same namespace as the logging operator.

    For the details of the ClusterOutput custom resource, see ClusterOutput.

    YAML Examples​

    Once logging is installed, you can use these examples to help craft your own logging pipeline.

    Cluster Output to ElasticSearch​

    Let's say you wanted to send all logs in your cluster to an elasticsearch cluster. First, we create a cluster Output.

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterOutput
    metadata:
      name: "example-es"
      namespace: "cattle-logging-system"
    spec:
      elasticsearch:
        host: elasticsearch.example.com
        port: 9200
        scheme: http

    We have created this ClusterOutput, without elasticsearch configuration, in the same namespace as our operator: cattle-logging-system.. Any time we create a ClusterFlow or ClusterOutput, we have to put it in the cattle-logging-system namespace.

    Now that we have configured where we want the logs to go, let's configure all logs to go to that ClusterOutput.

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterFlow
    metadata:
      name: "all-logs"
      namespace: "cattle-logging-system"
    spec:
      globalOutputRefs:
        - "example-es"

    We should now see our configured index with logs in it.

    Output to Splunk​

    What if we have an application team who only wants logs from a specific namespaces sent to a splunk server? For this case, we can use namespaced Outputs and Flows.

    Before we start, let's set up that team's application: coolapp.

    apiVersion: v1
    kind: Namespace
    metadata:
      name: devteam
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: coolapp
      namespace: devteam
      labels:
        app: coolapp
    spec:
      replicas: 2
      selector:
        matchLabels:
          app: coolapp
      template:
        metadata:
          labels:
            app: coolapp
        spec:
          containers:
            - name: generator
              image: paynejacob/loggenerator:latest

    With coolapp running, we will follow a similar path as when we created a ClusterOutput. However, unlike ClusterOutputs, we create our Output in our application's namespace.

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: Output
    metadata:
      name: "devteam-splunk"
      namespace: "devteam"
    spec:
      splunkHec:
        hec_host: splunk.example.com
        hec_port: 8088
        protocol: http

    Once again, let's feed our Output some logs:

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: Flow
    metadata:
      name: "devteam-logs"
      namespace: "devteam"
    spec:
      localOutputRefs:
        - "devteam-splunk"

    Output to Syslog​

    Let's say you wanted to send all logs in your cluster to an syslog server. First, we create a ClusterOutput:

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterOutput
    metadata:
      name: "example-syslog"
      namespace: "cattle-logging-system"
    spec:
      syslog:
        buffer:
          timekey: 30s
          timekey_use_utc: true
          timekey_wait: 10s
          flush_interval: 5s
        format:
          type: json
          app_name_field: test
        host: syslog.example.com
        insecure: true
        port: 514
        transport: tcp

    Now that we have configured where we want the logs to go, let's configure all logs to go to that Output.

    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterFlow
    metadata:
      name: "all-logs"
      namespace: cattle-logging-system
    spec:
      globalOutputRefs:
        - "example-syslog"

    Unsupported Outputs​

    For the final example, we create an Output to write logs to a destination that is not supported out of the box:

    Note on syslog As of Rancher v2.5.4, syslog is a supported Output. However, this example still provides an overview on using unsupported plugins.

    apiVersion: v1
    kind: Secret
    metadata:
      name: syslog-config
      namespace: cattle-logging-system
    type: Opaque
    stringData:
      fluent-bit.conf: |
        [INPUT]
            Name              forward
            Port              24224

        [OUTPUT]
            Name              syslog
            InstanceName      syslog-output
            Match             *
            Addr              syslog.example.com
            Port              514
            Cluster           ranchers

    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: fluentbit-syslog-forwarder
      namespace: cattle-logging-system
      labels:
        output: syslog
    spec:
      selector:
        matchLabels:
          output: syslog
      template:
        metadata:
          labels:
            output: syslog
        spec:
          containers:
          - name: fluentbit
            image: paynejacob/fluent-bit-out-syslog:latest
            ports:
              - containerPort: 24224
            volumeMounts:
              - mountPath: "/fluent-bit/etc/"
                name: configuration
          volumes:
          - name: configuration
            secret:
              secretName: syslog-config
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: syslog-forwarder
      namespace: cattle-logging-system
    spec:
      selector:
        output: syslog
      ports:
        - protocol: TCP
          port: 24224
          targetPort: 24224
    ---
    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterFlow
    metadata:
      name: all-logs
      namespace: cattle-logging-system
    spec:
      globalOutputRefs:
        - syslog
    ---
    apiVersion: logging.banzaicloud.io/v1beta1
    kind: ClusterOutput
    metadata:
      name: syslog
      namespace: cattle-logging-system
    spec:
      forward:
        servers:
          - host: "syslog-forwarder.cattle-logging-system"
        require_ack_response: false
        ignore_network_errors_at_startup: false

    Let's break down what is happening here. First, we create a deployment of a container that has the additional syslog plugin and accepts logs forwarded from another fluentd. Next we create an Output configured as a forwarder to our deployment. The deployment fluentd will then forward all logs to the configured syslog destination.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/logging-architecture.html b/v2.5/explanations/integrations-in-rancher/logging/logging-architecture.html index 2372aaf4a76..219bb8ad86d 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/logging-architecture.html +++ b/v2.5/explanations/integrations-in-rancher/logging/logging-architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
    Version: v2.5

    Architecture

    This section summarizes the architecture of the Rancher logging application.

    For more details about how the Banzai Cloud Logging operator works, see the official documentation.

    Changes in Rancher v2.5​

    The following changes were introduced to logging in Rancher v2.5:

    • The Banzai Cloud Logging operator now powers Rancher's logging solution in place of the former, in-house solution.
    • Fluent Bit is now used to aggregate the logs, and Fluentd is used for filtering the messages and routing them to the Outputs. Previously, only Fluentd was used.
    • Logging can be configured with a Kubernetes manifest, because logging now uses a Kubernetes operator with Custom Resource Definitions.
    • We now support filtering logs.
    • We now support writing logs to multiple Outputs.
    • We now always collect Control Plane and etcd logs.

    How the Banzai Cloud Logging Operator Works​

    The Logging operator automates the deployment and configuration of a Kubernetes logging pipeline. It deploys and configures a Fluent Bit DaemonSet on every node to collect container and application logs from the node file system.

    Fluent Bit queries the Kubernetes API and enriches the logs with metadata about the pods, and transfers both the logs and the metadata to Fluentd. Fluentd receives, filters, and transfers logs to multiple Outputs.

    The following custom resources are used to define how logs are filtered and sent to their Outputs:

    • A Flow is a namespaced custom resource that uses filters and selectors to route log messages to the appropriate Outputs.
    • A ClusterFlow is used to route cluster-level log messages.
    • An Output is a namespaced resource that defines where the log messages are sent.
    • A ClusterOutput defines an Output that is available from all Flows and ClusterFlows.

    Each Flow must reference an Output, and each ClusterFlow must reference a ClusterOutput.

    The following figure from the Banzai documentation shows the new logging architecture:

    How the Banzai Cloud Logging Operator Works with Fluentd and Fluent Bit

    How the Banzai Cloud Logging Operator Works with Fluentd

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html b/v2.5/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html index 0a0c05388eb..d2441b3979f 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html +++ b/v2.5/explanations/integrations-in-rancher/logging/logging-helm-chart-options.html @@ -5,14 +5,14 @@ rancher-logging Helm Chart Options | Rancher Manager - +
    Version: v2.5

    rancher-logging Helm Chart Options

    Enable/Disable Windows Node Logging​

    Available as of v2.5.8

    You can enable or disable Windows node logging by setting global.cattle.windows.enabled to either true or false in the values.yaml.

    By default, Windows node logging will be enabled if the Cluster Explorer UI is used to install the logging application on a Windows cluster.

    In this scenario, setting global.cattle.windows.enabled to false will disable Windows node logging on the cluster. When disabled, logs will still be collected from Linux nodes within the Windows cluster.

    Note: Currently an issue exists where Windows nodeAgents are not deleted when performing a helm upgrade after disabling Windows logging in a Windows cluster. In this scenario, users may need to manually remove the Windows nodeAgents if they are already installed.

    Working with a Custom Docker Root Directory​

    Applies to v2.5.6+

    If using a custom Docker root directory, you can set global.dockerRootDirectory in values.yaml.

    This will ensure that the Logging CRs created will use your specified path rather than the default Docker data-root location.

    Note that this only affects Linux nodes.

    If there are any Windows nodes in the cluster, the change will not be applicable to those nodes.

    Adding NodeSelector Settings and Tolerations for Custom Taints​

    You can add your own nodeSelector settings and add tolerations for additional taints by editing the logging Helm chart values. For details, see this page.

    Enabling the Logging Application to Work with SELinux​

    Available as of v2.5.8

    Requirements: Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8.

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8.

    To use Logging v2 with SELinux, we recommend installing the rancher-selinux RPM according to the instructions on this page.

    Then, when installing the logging application, configure the chart to be SELinux aware by changing global.seLinux.enabled to true in the values.yaml.

    Additional Logging Sources​

    By default, Rancher collects logs for control plane components and node components for all cluster types.

    In some cases, Rancher may be able to collect additional logs.

    The following table summarizes the sources where additional logs may be collected for each node types:

    Logging SourceLinux Nodes (including in Windows cluster)Windows Nodes
    RKE✓✓
    RKE2✓
    K3s✓
    AKS✓
    EKS✓
    GKE✓

    To enable hosted Kubernetes providers as additional logging sources, go to Cluster Explorer > Logging > Chart Options and select the Enable enhanced cloud provider logging option.

    When enabled, Rancher collects all additional node and control plane logs the provider has made available, which may vary between providers

    If you're already using a cloud provider's own logging solution such as AWS CloudWatch or Google Cloud operations suite (formerly Stackdriver), it is not necessary to enable this option as the native solution will have unrestricted access to all logs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html b/v2.5/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html index 1e8baed007c..9f6d754c7fc 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html +++ b/v2.5/explanations/integrations-in-rancher/logging/migrate-to-rancher-v2.5+-logging.html @@ -5,13 +5,13 @@ Migrating to Rancher v2.5 Logging | Rancher Manager - +
    Version: v2.5

    Migrating to Rancher v2.5 Logging

    Starting in v2.5, the logging feature available within Rancher has been completely overhauled. The logging operator from Banzai Cloud has been adopted; Rancher configures this tooling for use when deploying logging.

    Among the many features and changes in the new logging functionality is the removal of project-specific logging configurations. Instead, one now configures logging at the namespace level. Cluster-level logging remains available, but configuration options differ.

    Note: The pre-v2.5 user interface is now referred to as the Cluster Manager. The v2.5+ dashboard is referred to as the Cluster Explorer.

    Installation​

    To install logging in Rancher v2.5+, refer to the installation instructions.

    Terminology​

    In v2.5, logging configuration is centralized under a Logging menu option available in the Cluster Explorer. It is from this menu option that logging for both cluster and namespace is configured.

    Note: Logging is installed on a per-cluster basis. You will need to navigate between clusters to configure logging for each cluster.

    There are four key concepts to understand for v2.5+ logging:

    1. Outputs

      Outputs are a configuration resource that determine a destination for collected logs. This is where settings for aggregators such as ElasticSearch, Kafka, etc. are stored. Outputs are namespaced resources.

    2. Flows

      Flows are a configuration resource that determine collection, filtering, and destination rules for logs. It is within a flow that one will configure what logs to collect, how to mutate or filter them, and which Outputs to send the logs to. Flows are namespaced resources, and can connect either to an Output in the same namespace, or a ClusterOutput.

    3. ClusterOutputs

      ClusterOutputs serve the same functionality as Outputs, except they are a cluster-scoped resource. ClusterOutputs are necessary when collecting logs cluster-wide, or if you wish to provide an Output to all namespaces in your cluster.

    4. ClusterFlows

      ClusterFlows serve the same function as Flows, but at the cluster level. They are used to configure log collection for an entire cluster, instead of on a per-namespace level. ClusterFlows are also where mutations and filters are defined, same as Flows (in functionality).

    Cluster Logging​

    To configure cluster-wide logging for v2.5+ logging, one needs to set up a ClusterFlow. This object defines the source of logs, any transformations or filters to be applied, and finally the Output (or Outputs) for the logs.

    Important: ClusterFlows must be defined within the cattle-logging-system namespace. ClusterFlows will not work if defined in any other namespace.

    In legacy logging, in order to collect logs from across the entire cluster, one only needed to enable cluster-level logging and define the desired Output. This basic approach remains in v2.5+ logging. To replicate legacy cluster-level logging, follow these steps:

    1. Define a ClusterOutput according to the instructions found under Output Configuration
    2. Create a ClusterFlow, ensuring that it is set to be created in the cattle-logging-system namespace
      1. Remove all Include and Exclude rules from the Flow definition. This ensures that all logs are gathered.
      2. You do not need to configure any filters if you do not wish - default behavior does not require their creation
      3. Define your cluster Output or Outputs

    This will result in logs from all sources in the cluster (all pods, and all system components) being collected and sent to the Output or Outputs you defined in the ClusterFlow.

    Project Logging​

    Logging in v2.5+ is not project-aware. This means that in order to collect logs from pods running in project namespaces, you will need to define Flows for those namespaces.

    To collect logs from a specific namespace, follow these steps:

    1. Define an Output or ClusterOutput according to the instructions found under Output Configuration
    2. Create a Flow, ensuring that it is set to be created in the namespace in which you want to gather logs.
      1. If you wish to define Include or Exclude rules, you may do so. Otherwise, removal of all rules will result in all pods in the target namespace having their logs collected.
      2. You do not need to configure any filters if you do not wish - default behavior does not require their creation
      3. Define your outputs - these can be either ClusterOutput or Output objects.

    This will result in logs from all sources in the namespace (pods) being collected and sent to the Output (or Outputs) you defined in your Flow.

    To collect logs from a project, repeat the above steps for every namespace within the project. Alternatively, you can label your project workloads with a common label (e.g. project=my-project) and use a ClusterFlow to collect logs from all pods matching this label.

    Output Configuration​

    In legacy logging, there are five logging destinations to choose from: Elasticsearch, Splunk, Kafka, Fluentd, and Syslog. With the exception of Syslog, all of these destinations are available in logging v2.5+.

    Elasticsearch​

    Legacy Loggingv2.5+ LoggingNotes
    EndpointTarget -> HostMake sure to specify Scheme (https/http), as well as Port
    X-Pack Security -> UsernameAccess -> User
    X-Pack Security -> PasswordAccess -> PasswordPassword must now be stored in a secret
    SSL Configuration -> Client Private KeySSL -> Client KeyKey must now be stored in a secret
    SSL Configuration -> Client CertificateSSL -> Client CertCertificate must now be stored in a secret
    SSL Configuration -> Client Key PasswordSSL -> Client Key PassPassword must now be stored in a secret
    SSL Configuration -> Enabled SSL VerificationSSL -> Certificate Authority FileCertificate must now be stored in a secret

    In legacy logging, indices were automatically created according to the format in the "Index Patterns" section. In v2.5 logging, default behavior has been changed to logging to a single index. You can still configure index pattern functionality on the Output object by editing as YAML and inputting the following values:

    ...
    spec:
      elasticsearch:
        ...
        logstash_format: true
        logstash_prefix: <desired prefix>
        logstash_dateformat: "%Y-%m-%d"

    Replace <desired prefix> with the prefix for the indices that will be created. In legacy logging, this defaulted to the name of the cluster.

    Splunk​

    Legacy Loggingv2.5+ LoggingNotes
    HEC Configuration -> EndpointTarget -> HostProtocol (https/http) and port must be defined separately from the host
    HEC Configuration -> TokenAccess -> TokenToken must now be stored as a secret
    HEC Configuration -> IndexEdit as YAML -> indexindex field must be added as YAML key under spec.splunkHec
    HEC Configuration -> SourceEdit as YAML -> sourcesource field must be added as YAML key under spec.splunkHec
    SSL Configuration -> Client Private KeyEdit as YAML -> client_keyclient_key field must be added as YAML key under spec.splunkHec. See (1)
    SSL Configuration -> Client CertificateEdit as YAML -> client_certclient_cert field must be added as YAML key under spec.splunkHec. See (1)
    SSL Configuration -> Client Key PasswordNot SupportedSpecifying a password for the client private key is not currently supported.
    SSL Configuration -> SSL VerifyEdit as YAML -> ca_file or ca_pathca_file or ca_path field must be added as YAML key under spec.splunkHec. See (2)

    (1) client_key and client_cert values must be paths to the key and cert files, respectively. These files must be mounted into the rancher-logging-fluentd pod in order to be used.

    (2) Users can configure either ca_file (a path to a PEM-encoded CA certificate) or ca_path (a path to a directory containing CA certificates in PEM format). These files must be mounted into the rancher-logging-fluentd pod in order to be used.

    Kafka​

    Legacy Loggingv2.5+ LoggingNotes
    Kafka Configuration -> Endpoint Type-Zookeeper is no longer supported as an endpoint type
    Kafka Configuration -> EndpointTarget -> BrokersComma-separated list of brokers (host:port)
    Kafka Configuration -> TopicTarget -> Default Topic
    SSL Configuration -> Client Private KeySSL -> SSL Client CertCertificate must be stored as a secret
    SSL Configuration -> Client CertificateSSL -> SSL Client Cert KeyKey must be stored as a secret
    SSL Configuration -> CA Certificate PEMSSL -> SSL CA CertCertificate must be stored as a secret
    SASL Configuration -> UsernameAccess -> UsernameUsername must be stored in a secret
    SASL Configuration -> PasswordAccess -> PasswordPassword must be stored in a secret
    SASL Configuration -> Scram MechanismAccess -> Scram MechanismInput mechanism as string, e.g. "sha256" or "sha512"

    Fluentd​

    As of v2.5.2, it is only possible to add a single Fluentd server using the "Edit as Form" option. To add multiple servers, edit the Output as YAML and input multiple servers.

    Legacy Loggingv2.5+ LoggingNotes
    Fluentd Configuration -> EndpointTarget -> Host, PortInput the host and port separately
    Fluentd Configuration -> Shared KeyAccess -> Shared KeyShared key must be stored as a secret
    Fluentd Configuration -> UsernameAccess -> UsernameUsername must be stored as a secret
    Fluentd Configuration -> PasswordAccess -> PasswordPassword must be stored as a secret
    Fluentd Configuration -> HostnameEdit as YAML -> hosthost field set as YAML key under spec.forward.servers[n]
    Fluentd Configuration -> WeightEdit as YAML -> weightweight field set as YAML key under spec.forward.servers[n]
    SSL Configuration -> Use TLS-Do not need to explicitly enable. Define client cert fields instead.
    SSL Configuration -> Client Private KeyEdit as YAML -> tls_private_key_pathField set as YAML key under spec.forward. See (1)
    SSL Configuration -> Client CertificateEdit as YAML -> tls_client_cert_pathField set as YAML key under spec.forward. See (1)
    SSL Configuration -> Client Key PasswordEdit as YAML -> tls_client_private_key_passphraseField set as YAML key under spec.forward. See (1)
    SSL Configuration -> SSL VerifyEdit as YAML -> tls_insecure_modeField set as YAML key under spec.forward. Default: false
    SSL Configuration -> CA Certificate PEMEdit as YAML -> tls_cert_pathField set as YAML key under spec.forward. See (1)
    Enable Gzip Compression-No longer supported in v2.5+ logging

    (1) These values are to be specified as paths to files. Those files must be mounted into the rancher-logging-fluentd pod in order to be used.

    Syslog​

    As of v2.5.2, syslog is not currently supported for Outputs using v2.5+ logging.

    Custom Log Fields​

    In order to add custom log fields, you will need to add the following YAML to your Flow configuration:

    ...
    spec:
      filters:
        - record_modifier:
            records:
            - foo: "bar"

    (replace foo: "bar" with custom log fields you wish to add)

    System Logging​

    In legacy logging, collecting logs from system components was accomplished by checking a box labeled "Include System Log" when setting up cluster logging. In v2.5+ logging, system logs are gathered in one of two ways:

    1. Gather all cluster logs, not specifying any match or exclusion rules. This results in all container logs from the cluster being collected, which includes system logs.
    2. Specifically target system logs by adding match rules for system components. Specific match rules depend on the component being collected.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/rbac-for-logging.html b/v2.5/explanations/integrations-in-rancher/logging/rbac-for-logging.html index 094f35e414c..a10a3e175c7 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/rbac-for-logging.html +++ b/v2.5/explanations/integrations-in-rancher/logging/rbac-for-logging.html @@ -5,13 +5,13 @@ Role-based Access Control for Logging | Rancher Manager - +
    Version: v2.5

    Role-based Access Control for Logging

    Rancher logging has two roles, logging-admin and logging-view.

    • logging-admin gives users full access to namespaced Flows and Outputs
    • logging-view allows users to view namespaced Flows and Outputs, and ClusterFlows and ClusterOutputs

    Why choose one role over the other? Edit access to ClusterFlow and ClusterOutput resources is powerful. Any user with it has edit access for all logs in the cluster.

    In Rancher, the cluster administrator role is the only role with full access to all rancher-logging resources. Cluster members are not able to edit or read any logging resources. Project owners and members have the following privileges:

    Project OwnersProject Members
    able to create namespaced Flows and Outputs in their projects' namespacesonly able to view the Flows and Outputs in projects' namespaces
    can collect logs from anything in their projects' namespacescannot collect any logs in their projects' namespaces

    Both project owners and project members require at least one namespace in their project to use logging. If they do not, then they may not see the logging button in the top nav dropdown.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/logging/taints-and-tolerations.html b/v2.5/explanations/integrations-in-rancher/logging/taints-and-tolerations.html index b37cee00cdd..eff4d306850 100644 --- a/v2.5/explanations/integrations-in-rancher/logging/taints-and-tolerations.html +++ b/v2.5/explanations/integrations-in-rancher/logging/taints-and-tolerations.html @@ -5,7 +5,7 @@ Working with Taints and Tolerations | Rancher Manager - + @@ -16,7 +16,7 @@ Moreover, most logging stack pods run on Linux only and have a nodeSelecto The logging stack pods have tolerations for this taint, which enables them to run on Linux nodes. Moreover, we can populate the nodeSelector to ensure that our pods only run on Linux nodes.

    This example Pod YAML file shows a nodeSelector being used with a toleration:

    apiVersion: v1
    kind: Pod
    # metadata...
    spec:
      # containers...
      tolerations:
        - key: cattle.io/os
          operator: "Equal"
          value: "linux"
          effect: NoSchedule
      nodeSelector:
        kubernetes.io/os: linux

    In the above example, we ensure that our pod only runs on Linux nodes, and we add a toleration for the taint we have on all of our Linux nodes.

    You can do the same with Rancher's existing taints, or with your own custom ones.

    Adding NodeSelector Settings and Tolerations for Custom Taints​

    If you would like to add your own nodeSelector settings, or if you would like to add tolerations for additional taints, you can pass the following to the chart's values.

    tolerations:
      # insert tolerations...
    nodeSelector:
      # insert nodeSelector...

    These values will add both settings to the fluentd, fluentbit, and logging-operator containers. Essentially, these are global settings for all pods in the logging stack.

    However, if you would like to add tolerations for only the fluentbit container, you can add the following to the chart's values.

    fluentbit_tolerations:
      # insert tolerations list for fluentbit containers only...
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/longhorn.html b/v2.5/explanations/integrations-in-rancher/longhorn.html index 6f204b86a0d..eb88c62562b 100644 --- a/v2.5/explanations/integrations-in-rancher/longhorn.html +++ b/v2.5/explanations/integrations-in-rancher/longhorn.html @@ -5,13 +5,13 @@ Longhorn - Cloud native distributed block storage for Kubernetes | Rancher Manager - +
    Version: v2.5

    Longhorn - Cloud native distributed block storage for Kubernetes

    Longhorn is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.

    Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI. You can learn more about its architecture here.

    With Longhorn, you can:

    • Use Longhorn volumes as persistent storage for the distributed stateful applications in your Kubernetes cluster
    • Partition your block storage into Longhorn volumes so that you can use Kubernetes volumes with or without a cloud provider
    • Replicate block storage across multiple nodes and data centers to increase availability
    • Store backup data in external storage such as NFS or AWS S3
    • Create cross-cluster disaster recovery volumes so that data from a primary Kubernetes cluster can be quickly recovered from backup in a second Kubernetes cluster
    • Schedule recurring snapshots of a volume, and schedule recurring backups to NFS or S3-compatible secondary storage
    • Restore volumes from backup
    • Upgrade Longhorn without disrupting persistent volumes
    Longhorn Dashboard

    Longhorn Dashboard

    New in Rancher v2.5​

    Before Rancher v2.5, Longhorn could be installed as a Rancher catalog app. In Rancher v2.5, the catalog system was replaced by the Apps & Marketplace, and it became possible to install Longhorn as an app from that page.

    The Cluster Explorer now allows you to manipulate Longhorn's Kubernetes resources from the Rancher UI. So now you can control the Longhorn functionality with the Longhorn UI, or with kubectl, or by manipulating Longhorn's Kubernetes custom resources in the Rancher UI.

    These instructions assume you are using Rancher v2.5, but Longhorn can be installed with earlier Rancher versions. For documentation about installing Longhorn as a catalog app using the legacy Rancher UI, refer to the Longhorn documentation.

    Installing Longhorn with Rancher​

    1. Fulfill all Installation Requirements.
    2. Go to the Cluster Explorer in the Rancher UI.
    3. Click Apps.
    4. Click longhorn.
    5. Optional: To customize the initial settings, click Longhorn Default Settings and edit the configuration. For help customizing the settings, refer to the Longhorn documentation.
    6. Click Install.

    Result: Longhorn is deployed in the Kubernetes cluster.

    Accessing Longhorn from the Rancher UI​

    1. From the Cluster Explorer," go to the top left dropdown menu and click Cluster Explorer > Longhorn.**
    2. On this page, you can edit Kubernetes resources managed by Longhorn. To view the Longhorn UI, click the Longhorn button in the Overview section.

    Result: You will be taken to the Longhorn UI, where you can manage your Longhorn volumes and their replicas in the Kubernetes cluster, as well as secondary backups of your Longhorn storage that may exist in another Kubernetes cluster or in S3.

    Uninstalling Longhorn from the Rancher UI​

    1. Click Cluster Explorer > Apps & Marketplace.
    2. Click Installed Apps.
    3. Go to the longhorn-system namespace and check the boxes next to the longhorn and longhorn-crd apps.
    4. Click Delete, and confirm Delete.

    Result: Longhorn is uninstalled.

    GitHub Repository​

    The Longhorn project is available here.

    Documentation​

    The Longhorn documentation is here.

    Architecture​

    Longhorn creates a dedicated storage controller for each volume and synchronously replicates the volume across multiple replicas stored on multiple nodes.

    The storage controller and replicas are themselves orchestrated using Kubernetes.

    You can learn more about its architecture here.

    Longhorn Architecture

    Longhorn Architecture

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html index d8bcd106baa..278a4f7aa89 100644 --- a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html +++ b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/built-in-dashboards.html @@ -5,13 +5,13 @@ Built-in Dashboards | Rancher Manager - +
    Version: v2.5

    Built-in Dashboards

    Grafana UI​

    Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored. Create, explore, and share dashboards with your team and foster a data driven culture.

    To see the default dashboards for time series data visualization, go to the Grafana UI.

    Customizing Grafana​

    To view and customize the PromQL queries powering the Grafana dashboard, see this page.

    Persistent Grafana Dashboards​

    To create a persistent Grafana dashboard, see this page.

    Access to Grafana​

    For information about role-based access control for Grafana, see this section.

    Alertmanager UI​

    When rancher-monitoring is installed, the Prometheus Alertmanager UI is deployed, allowing you to view your alerts and the current Alertmanager configuration.

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    Accessing the Alertmanager UI​

    The Alertmanager UI lets you see the most recently fired alerts.

    Prerequisite: The rancher-monitoring application must be installed.

    To see the Alertmanager UI, go to the Cluster Explorer. In the top left corner, click Cluster Explorer > Monitoring. Then click Alertmanager.

    Result: The Alertmanager UI opens in a new tab. For help with configuration, refer to the official Alertmanager documentation.

    The Alertmanager UI

    Alertmanager UI

    Viewing Default Alerts​

    To see alerts that are fired by default, go to the Alertmanager UI and click Expand all groups.

    Prometheus UI​

    By default, the kube-state-metrics service provides a wealth of information about CPU and memory utilization to the monitoring application. These metrics cover Kubernetes resources across namespaces. This means that in order to see resource metrics for a service, you don't need to create a new ServiceMonitor for it. Because the data is already in the time series database, you can go to the Prometheus UI and run a PromQL query to get the information. The same query can be used to configure a Grafana dashboard to show a graph of those metrics over time.

    To see the Prometheus UI, install rancher-monitoring. Then go to the Cluster Explorer. In the top left corner, click Cluster Explorer > Monitoring. Then click Prometheus Graph.

    Prometheus Graph UI

    Prometheus Graph UI

    Viewing the Prometheus Targets​

    To see what services you are monitoring, you will need to see your targets. Targets are set up by ServiceMonitors and PodMonitors as sources to scrape metrics from. You won't need to directly edit targets, but the Prometheus UI can be useful for giving you an overview of all of the sources of metrics that are being scraped.

    To see the Prometheus Targets, install rancher-monitoring. Then go to the Cluster Explorer. In the top left corner, click Cluster Explorer > Monitoring. Then click Prometheus Targets.

    Targets in the Prometheus UI

    Prometheus Targets UI

    Viewing the PrometheusRules​

    When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the spec of the Rule itself contains labels that are used by Alertmanager to figure out which Route should receive a certain Alert.

    To see the PrometheusRules, install rancher-monitoring. Then go to the Cluster Explorer. In the top left corner, click Cluster Explorer > Monitoring. Then click Prometheus Rules.

    You can also see the rules in the Prometheus UI:

    Rules in the Prometheus UI

    PrometheusRules UI

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html index 97dac9ac849..c8f094ee0fa 100644 --- a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html +++ b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/how-monitoring-works.html @@ -5,14 +5,14 @@ How Monitoring Works | Rancher Manager - +
    Version: v2.5

    How Monitoring Works

    1. Architecture Overview​

    The following sections describe how data flows through the Monitoring V2 application:

    Prometheus Operator​

    Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created. When the Prometheus configuration resources are created, Prometheus Operator calls the Prometheus API to sync the new configuration. As the diagram at the end of this section shows, the Prometheus Operator acts as the intermediary between Prometheus and Kubernetes, calling the Prometheus API to synchronize Prometheus with the monitoring-related resources in Kubernetes.

    ServiceMonitors and PodMonitors​

    ServiceMonitors and PodMonitors declaratively specify targets, such as Services and Pods, that need to be monitored.

    • Targets are scraped on a recurring schedule based on the configured Prometheus scrape interval, and the metrics that are scraped are stored into the Prometheus Time Series Database (TSDB).

    • In order to perform the scrape, ServiceMonitors and PodMonitors are defined with label selectors that determine which Services or Pods should be scraped and endpoints that determine how the scrape should happen on the given target, e.g., scrape/metrics in TCP 10252, proxying through IP addr x.x.x.x.

    • Out of the box, Monitoring V2 comes with certain pre-configured exporters that are deployed based on the type of Kubernetes cluster that it is deployed on. For more information, see Scraping and Exposing Metrics.

    How PushProx Works​

    • Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. The Kubernetes components that expose metrics to Prometheus through PushProx are the following: kube-controller-manager, kube-scheduler, etcd, and kube-proxy.

    • For each PushProx exporter, we deploy one PushProx client onto all target nodes. For example, a PushProx client is deployed onto all controlplane nodes for kube-controller-manager, all etcd nodes for kube-etcd, and all nodes for kubelet.

    • We deploy exactly one PushProx proxy per exporter. The process for exporting metrics is as follows:

    1. The PushProx Client establishes an outbound connection with the PushProx Proxy.
    2. The client then polls the proxy for scrape requests that have come into the proxy.
    3. When the proxy receives a scrape request from Prometheus, the client sees it as a result of the poll.
    4. The client scrapes the internal component.
    5. The internal component responds by pushing metrics back to the proxy.

    Process for Exporting Metrics with PushProx:

    Process for Exporting Metrics with PushProx

    PrometheusRules​

    PrometheusRules allow users to define rules for what metrics or time series database queries should result in alerts being fired. Rules are evaluated on an interval.

    • Recording rules create a new time series based on existing series that have been collected. They are frequently used to precompute complex queries.
    • Alerting rules run a particular query and fire an alert from Prometheus if the query evaluates to a non-zero value.

    Alert Routing​

    Once Prometheus determines that an alert needs to be fired, alerts are forwarded to Alertmanager.

    • Alerts contain labels that come from the PromQL query itself and additional labels and annotations that can be provided as part of specifying the initial PrometheusRule.

    • Before receiving any alerts, Alertmanager will use the routes and receivers specified in its configuration to form a routing tree on which all incoming alerts are evaluated. Each node of the routing tree can specify additional grouping, labeling, and filtering that needs to happen based on the labels attached to the Prometheus alert. A node on the routing tree (usually a leaf node) can also specify that an alert that reaches it needs to be sent out to a configured Receiver, e.g., Slack, PagerDuty, SMS, etc. Note that Alertmanager will send an alert first to alertingDriver, then alertingDriver will send or forward alert to the proper destination.

    • Routes and receivers are also stored in the Kubernetes API via the Alertmanager Secret. When the Secret is updated, Alertmanager is also updated automatically. Note that routing occurs via labels only (not via annotations, etc.).

    How data flows through the monitoring application:

    2. How Prometheus Works​

    Storing Time Series Data​

    After collecting metrics from exporters, Prometheus stores the time series in a local on-disk time series database. Prometheus optionally integrates with remote systems, but rancher-monitoring uses local storage for the time series database.

    Once stored, users can query this TSDB using PromQL, the query language for Prometheus.

    PromQL queries can be visualized in one of two ways:

    1. By supplying the query in Prometheus's Graph UI, which will show a simple graphical view of the data.
    2. By creating a Grafana Dashboard that contains the PromQL query and additional formatting directives that label axes, add units, change colors, use alternative visualizations, etc.

    Defining Rules for Prometheus​

    Rules define queries that Prometheus needs to execute on a regular evaluationInterval to perform certain actions, such as firing an alert (alerting rules) or precomputing a query based on others existing in its TSDB (recording rules). These rules are encoded in PrometheusRules custom resources. When PrometheusRule custom resources are created or updated, the Prometheus Operator observes the change and calls the Prometheus API to synchronize the set of rules that Prometheus is currently evaluating on a regular interval.

    A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:

    • The name of the new alert or record
    • A PromQL expression for the new alert or record
    • Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
    • Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.

    On evaluating a rule, Prometheus will execute the provided PromQL query, add additional provided labels (or annotations - only for alerting rules), and execute the appropriate action for the rule. For example, an Alerting Rule that adds team: front-end as a label to the provided PromQL query will append that label to the fired alert, which will allow Alertmanager to forward the alert to the correct Receiver.

    Alerting and Recording Rules​

    Prometheus doesn't maintain the state of whether alerts are active. It fires alerts repetitively at every evaluation interval, relying on Alertmanager to group and filter the alerts into meaningful notifications.

    The evaluation_interval constant defines how often Prometheus evaluates its alerting rules against the time series database. Similar to the scrape_interval, the evaluation_interval also defaults to one minute.

    The rules are contained in a set of rule files. Rule files include both alerting rules and recording rules, but only alerting rules result in alerts being fired after their evaluation.

    For recording rules, Prometheus runs a query, then stores it as a time series. This synthetic time series is useful for storing the results of an expensive or time-consuming query so that it can be queried more quickly in the future.

    Alerting rules are more commonly used. Whenever an alerting rule evaluates to a positive number, Prometheus fires an alert.

    The Rule file adds labels and annotations to alerts before firing them, depending on the use case:

    • Labels indicate information that identifies the alert and could affect the routing of the alert. For example, if when sending an alert about a certain container, the container ID could be used as a label.

    • Annotations denote information that doesn't affect where an alert is routed, for example, a runbook or an error message.

    3. How Alertmanager Works​

    The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of the following tasks:

    • Deduplicating, grouping, and routing alerts to the correct receiver integration such as email, PagerDuty, or OpsGenie

    • Silencing and inhibition of alerts

    • Tracking alerts that fire over time

    • Sending out the status of whether an alert is currently firing, or if it is resolved

    Alerts Forwarded by alertingDrivers​

    When alertingDrivers are installed, this creates a Service that can be used as the receiver's URL for Teams or SMS, based on the alertingDriver's configuration. The URL in the Receiver points to the alertingDrivers; so the Alertmanager sends alert first to alertingDriver, then alertingDriver forwards or sends alert to the proper destination.

    Routing Alerts to Receivers​

    Alertmanager coordinates where alerts are sent. It allows you to group alerts based on labels and fire them based on whether certain labels are matched. One top-level route accepts all alerts. From there, Alertmanager continues routing alerts to receivers based on whether they match the conditions of the next route.

    While the Rancher UI forms only allow editing a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager Secret.

    Configuring Multiple Receivers​

    By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.

    By editing custom YAML in the Alertmanager or Receiver configuration, you can also send alerts to multiple notification systems. For more information, see the section on configuring Receivers.

    4. Monitoring V2 Specific Components​

    Prometheus Operator introduces a set of Custom Resource Definitions that allow users to deploy and manage Prometheus and Alertmanager instances by creating and modifying those custom resources on a cluster.

    Prometheus Operator will automatically update your Prometheus configuration based on the live state of the resources and configuration options that are edited in the Rancher UI.

    Resources Deployed by Default​

    By default, a set of resources curated by the kube-prometheus project are deployed onto your cluster as part of installing the Rancher Monitoring Application to set up a basic Monitoring/Alerting stack.

    The resources that get deployed onto your cluster to support this solution can be found in the rancher-monitoring Helm chart, which closely tracks the upstream kube-prometheus-stack Helm chart maintained by the Prometheus community with certain changes tracked in the CHANGELOG.md.

    Default Exporters​

    Monitoring V2 deploys three default exporters that provide additional metrics for Prometheus to store:

    1. node-exporter: exposes hardware and OS metrics for Linux hosts. For more information on node-exporter, refer to the upstream documentation.

    2. windows-exporter: exposes hardware and OS metrics for Windows hosts (only deployed on Windows clusters). For more information on windows-exporter, refer to the upstream documentation.

    3. kube-state-metrics: expose additional metrics that track the state of resources contained in the Kubernetes API (e.g., pods, workloads, etc.). For more information on kube-state-metrics, refer to the upstream documentation.

    ServiceMonitors and PodMonitors will scrape these exporters, as defined here. Prometheus stores these metrics, and you can query the results via either Prometheus's UI or Grafana.

    See the architecture section for more information on recording rules, alerting rules, and Alertmanager.

    Components Exposed in the Rancher UI​

    When the monitoring application is installed, you will be able to edit the following components in the Rancher UI:

    ComponentType of ComponentPurpose and Common Use Cases for Editing
    ServiceMonitorCustom resourceSets up Kubernetes Services to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource.
    PodMonitorCustom resourceSets up Kubernetes Pods to scrape custom metrics from. Automatically updates the scrape configuration in the Prometheus custom resource.
    ReceiverConfiguration block (part of Alertmanager)Modifies information on where to send an alert (e.g., Slack, PagerDuty, etc.) and any necessary information to send the alert (e.g., TLS certs, proxy URLs, etc.). Automatically updates the Alertmanager custom resource.
    RouteConfiguration block (part of Alertmanager)Modifies the routing tree that is used to filter, label, and group alerts based on labels and send them to the appropriate Receiver. Automatically updates the Alertmanager custom resource.
    PrometheusRuleCustom resourceDefines additional queries that need to trigger alerts or define materialized views of existing series that are within Prometheus's TSDB. Automatically updates the Prometheus custom resource.

    PushProx​

    PushProx allows Prometheus to scrape metrics across a network boundary, which prevents users from having to expose metrics ports for internal Kubernetes components on each node in a Kubernetes cluster.

    Since the metrics for Kubernetes components are generally exposed on the host network of nodes in the cluster, PushProx deploys a DaemonSet of clients that sit on the hostNetwork of each node and make an outbound connection to a single proxy that is sitting on the Kubernetes API. Prometheus can then be configured to proxy scrape requests through the proxy to each client, which allows it to scrape metrics from the internal Kubernetes components without requiring any inbound node ports to be open.

    Refer to Scraping Metrics with PushProx for more.

    5. Scraping and Exposing Metrics​

    Defining what Metrics are Scraped​

    ServiceMonitors and PodMonitors define targets that are intended for Prometheus to scrape. The Prometheus custom resource tells Prometheus which ServiceMonitors or PodMonitors it should use to find out where to scrape metrics from.

    The Prometheus Operator observes the ServiceMonitors and PodMonitors. When it observes that they are created or updated, it calls the Prometheus API to update the scrape configuration in the Prometheus custom resource and keep it in sync with the scrape configuration in the ServiceMonitors or PodMonitors. This scrape configuration tells Prometheus which endpoints to scrape metrics from and how it will label the metrics from those endpoints.

    Prometheus scrapes all of the metrics defined in its scrape configuration at every scrape_interval, which is one minute by default.

    The scrape configuration can be viewed as part of the Prometheus custom resource that is exposed in the Rancher UI.

    How the Prometheus Operator Sets up Metrics Scraping​

    The Prometheus Deployment or StatefulSet scrapes metrics, and the configuration of Prometheus is controlled by the Prometheus custom resources. The Prometheus Operator watches for Prometheus and Alertmanager resources, and when they are created, the Prometheus Operator creates a Deployment or StatefulSet for Prometheus or Alertmanager with the user-defined configuration.

    When the Prometheus Operator observes ServiceMonitors, PodMonitors, and PrometheusRules being created, it knows that the scrape configuration needs to be updated in Prometheus. It updates Prometheus by first updating the configuration and rules files in the volumes of Prometheus's Deployment or StatefulSet. Then it calls the Prometheus API to sync the new configuration, resulting in the Prometheus Deployment or StatefulSet to be modified in place.

    How Kubernetes Component Metrics are Exposed​

    Prometheus scrapes metrics from deployments known as exporters, which export the time series data in a format that Prometheus can ingest. In Prometheus, time series consist of streams of timestamped values belonging to the same metric and the same set of labeled dimensions.

    Scraping Metrics with PushProx​

    Certain internal Kubernetes components are scraped via a proxy deployed as part of Monitoring V2 called PushProx. For detailed information on PushProx, refer here and to the above architecture section.

    Scraping Metrics​

    The following Kubernetes components are directly scraped by Prometheus:

    • kubelet*
    • ingress-nginx**
    • coreDns/kubeDns
    • kube-api-server

    * You can optionally use hardenedKubelet.enabled to use a PushProx, but that is not the default.

    ** For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.

    Scraping Metrics Based on Kubernetes Distribution​

    Metrics are scraped differently based on the Kubernetes distribution. For help with terminology, refer here. For details, see the table below:

    How Metrics are Exposed to Prometheus
    Kubernetes ComponentRKERKE2KubeADMK3s
    kube-controller-managerrkeControllerManager.enabledrke2ControllerManager.enabledkubeAdmControllerManager.enabledk3sServer.enabled
    kube-schedulerrkeScheduler.enabledrke2Scheduler.enabledkubeAdmScheduler.enabledk3sServer.enabled
    etcdrkeEtcd.enabledrke2Etcd.enabledkubeAdmEtcd.enabledNot available
    kube-proxyrkeProxy.enabledrke2Proxy.enabledkubeAdmProxy.enabledk3sServer.enabled
    kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubeletCollects metrics directly exposed by kubelet
    ingress-nginx*Collects metrics directly exposed by kubelet, exposed by rkeIngressNginx.enabledCollects metrics directly exposed by kubelet, Exposed by rke2IngressNginx.enabledNot availableNot available
    coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDnsCollects metrics directly exposed by coreDns/kubeDns
    kube-api-serverCollects metrics directly exposed by kube-api-serverCollects metrics directly exposed by kube-api-serverCollects metrics directly exposed by kube-appi-serverCollects metrics directly exposed by kube-api-server

    * For RKE and RKE2 clusters, ingress-nginx is deployed by default and treated as an internal Kubernetes component.

    Terminology​

    • kube-scheduler: The internal Kubernetes component that uses information in the pod spec to decide on which node to run a pod.
    • kube-controller-manager: The internal Kubernetes component that is responsible for node management (detecting if a node fails), pod replication and endpoint creation.
    • etcd: The internal Kubernetes component that is the distributed key/value store which Kubernetes uses for persistent storage of all cluster information.
    • kube-proxy: The internal Kubernetes component that watches the API server for pods/services changes in order to maintain the network up to date.
    • kubelet: The internal Kubernetes component that watches the API server for pods on a node and makes sure they are running.
    • ingress-nginx: An Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer.
    • coreDns/kubeDns: The internal Kubernetes component responsible for DNS.
    • kube-api-server: The main internal Kubernetes component that is responsible for exposing APIs for the other master components.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html index 178edbd6713..cee0a74448d 100644 --- a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html +++ b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/promql-expressions.html @@ -5,13 +5,13 @@ PromQL Expression Reference | Rancher Manager - +
    Version: v2.5

    PromQL Expression Reference

    The PromQL expressions in this doc can be used to configure alerts.

    For more information about querying the Prometheus time series database, refer to the official Prometheus documentation.

    Cluster Metrics​

    Cluster CPU Utilization​

    CatalogExpression
    Detail1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance))
    Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])))

    Cluster Load Average​

    CatalogExpression
    Detail
    load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
    load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
    load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"}) by (instance)
    Summary
    load1sum(node_load1) by (instance) / count(node_cpu_seconds_total{mode="system"})
    load5sum(node_load5) by (instance) / count(node_cpu_seconds_total{mode="system"})
    load15sum(node_load15) by (instance) / count(node_cpu_seconds_total{mode="system"})

    Cluster Memory Utilization​

    CatalogExpression
    Detail1 - sum(node_memory_MemAvailable_bytes) by (instance) / sum(node_memory_MemTotal_bytes) by (instance)
    Summary1 - sum(node_memory_MemAvailable_bytes) / sum(node_memory_MemTotal_bytes)

    Cluster Disk Utilization​

    CatalogExpression
    Detail(sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance) - sum(node_filesystem_free_bytes{device!="rootfs"}) by (instance)) / sum(node_filesystem_size_bytes{device!="rootfs"}) by (instance)
    Summary(sum(node_filesystem_size_bytes{device!="rootfs"}) - sum(node_filesystem_free_bytes{device!="rootfs"})) / sum(node_filesystem_size_bytes{device!="rootfs"})

    Cluster Disk I/O​

    CatalogExpression
    Detail
    readsum(rate(node_disk_read_bytes_total[5m])) by (instance)
    writtensum(rate(node_disk_written_bytes_total[5m])) by (instance)
    Summary
    readsum(rate(node_disk_read_bytes_total[5m]))
    writtensum(rate(node_disk_written_bytes_total[5m]))

    Cluster Network Packets​

    CatalogExpression
    Detail
    receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    Summary
    receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

    Cluster Network I/O​

    CatalogExpression
    Detail
    receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m])) by (instance)
    Summary
    receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))
    transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*"}[5m]))

    Node Metrics​

    Node CPU Utilization​

    CatalogExpression
    Detailavg(irate(node_cpu_seconds_total{mode!="idle", instance=~"$instance"}[5m])) by (mode)
    Summary1 - (avg(irate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[5m])))

    Node Load Average​

    CatalogExpression
    Detail
    load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
    load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
    load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
    Summary
    load1sum(node_load1{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
    load5sum(node_load5{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})
    load15sum(node_load15{instance=~"$instance"}) / count(node_cpu_seconds_total{mode="system",instance=~"$instance"})

    Node Memory Utilization​

    CatalogExpression
    Detail1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})
    Summary1 - sum(node_memory_MemAvailable_bytes{instance=~"$instance"}) / sum(node_memory_MemTotal_bytes{instance=~"$instance"})

    Node Disk Utilization​

    CatalogExpression
    Detail(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"}) by (device)) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) by (device)
    Summary(sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"}) - sum(node_filesystem_free_bytes{device!="rootfs",instance=~"$instance"})) / sum(node_filesystem_size_bytes{device!="rootfs",instance=~"$instance"})

    Node Disk I/O​

    CatalogExpression
    Detail
    readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
    writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))
    Summary
    readsum(rate(node_disk_read_bytes_total{instance=~"$instance"}[5m]))
    writtensum(rate(node_disk_written_bytes_total{instance=~"$instance"}[5m]))

    Node Network Packets​

    CatalogExpression
    Detail
    receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    Summary
    receive-droppedsum(rate(node_network_receive_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    receive-errssum(rate(node_network_receive_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    receive-packetssum(rate(node_network_receive_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    transmit-droppedsum(rate(node_network_transmit_drop_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    transmit-errssum(rate(node_network_transmit_errs_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    transmit-packetssum(rate(node_network_transmit_packets_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

    Node Network I/O​

    CatalogExpression
    Detail
    receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m])) by (device)
    Summary
    receivesum(rate(node_network_receive_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))
    transmitsum(rate(node_network_transmit_bytes_total{device!~"lo | veth.* | docker.* | flannel.* | cali.* | cbr.*",instance=~"$instance"}[5m]))

    Etcd Metrics​

    Etcd Has a Leader​

    max(etcd_server_has_leader)

    Number of Times the Leader Changes​

    max(etcd_server_leader_changes_seen_total)

    Number of Failed Proposals​

    sum(etcd_server_proposals_failed_total)

    GRPC Client Traffic​

    CatalogExpression
    Detail
    insum(rate(etcd_network_client_grpc_received_bytes_total[5m])) by (instance)
    outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m])) by (instance)
    Summary
    insum(rate(etcd_network_client_grpc_received_bytes_total[5m]))
    outsum(rate(etcd_network_client_grpc_sent_bytes_total[5m]))

    Peer Traffic​

    CatalogExpression
    Detail
    insum(rate(etcd_network_peer_received_bytes_total[5m])) by (instance)
    outsum(rate(etcd_network_peer_sent_bytes_total[5m])) by (instance)
    Summary
    insum(rate(etcd_network_peer_received_bytes_total[5m]))
    outsum(rate(etcd_network_peer_sent_bytes_total[5m]))

    DB Size​

    CatalogExpression
    Detailsum(etcd_debugging_mvcc_db_total_size_in_bytes) by (instance)
    Summarysum(etcd_debugging_mvcc_db_total_size_in_bytes)

    Active Streams​

    CatalogExpression
    Detail
    lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) by (instance)
    watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) by (instance)
    Summary
    lease-watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Lease",grpc_type="bidi_stream"})
    watchsum(grpc_server_started_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"}) - sum(grpc_server_handled_total{grpc_service="etcdserverpb.Watch",grpc_type="bidi_stream"})

    Raft Proposals​

    CatalogExpression
    Detail
    appliedsum(increase(etcd_server_proposals_applied_total[5m])) by (instance)
    committedsum(increase(etcd_server_proposals_committed_total[5m])) by (instance)
    pendingsum(increase(etcd_server_proposals_pending[5m])) by (instance)
    failedsum(increase(etcd_server_proposals_failed_total[5m])) by (instance)
    Summary
    appliedsum(increase(etcd_server_proposals_applied_total[5m]))
    committedsum(increase(etcd_server_proposals_committed_total[5m]))
    pendingsum(increase(etcd_server_proposals_pending[5m]))
    failedsum(increase(etcd_server_proposals_failed_total[5m]))

    RPC Rate​

    CatalogExpression
    Detail
    totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m])) by (instance)
    failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m])) by (instance)
    Summary
    totalsum(rate(grpc_server_started_total{grpc_type="unary"}[5m]))
    failsum(rate(grpc_server_handled_total{grpc_type="unary",grpc_code!="OK"}[5m]))

    Disk Operations​

    CatalogExpression
    Detail
    commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m])) by (instance)
    fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m])) by (instance)
    Summary
    commit-called-by-backendsum(rate(etcd_disk_backend_commit_duration_seconds_sum[1m]))
    fsync-called-by-walsum(rate(etcd_disk_wal_fsync_duration_seconds_sum[1m]))

    Disk Sync Duration​

    CatalogExpression
    Detail
    walhistogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le))
    dbhistogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le))
    Summary
    walsum(histogram_quantile(0.99, sum(rate(etcd_disk_wal_fsync_duration_seconds_bucket[5m])) by (instance, le)))
    dbsum(histogram_quantile(0.99, sum(rate(etcd_disk_backend_commit_duration_seconds_bucket[5m])) by (instance, le)))

    Kubernetes Components Metrics​

    API Server Request Latency​

    CatalogExpression
    Detailavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance, verb) /1e+06
    Summaryavg(apiserver_request_latencies_sum / apiserver_request_latencies_count) by (instance) /1e+06

    API Server Request Rate​

    CatalogExpression
    Detailsum(rate(apiserver_request_count[5m])) by (instance, code)
    Summarysum(rate(apiserver_request_count[5m])) by (instance)

    Scheduling Failed Pods​

    CatalogExpression
    Detailsum(kube_pod_status_scheduled{condition="false"})
    Summarysum(kube_pod_status_scheduled{condition="false"})

    Controller Manager Queue Depth​

    CatalogExpression
    Detail
    volumessum(volumes_depth) by instance
    deploymentsum(deployment_depth) by instance
    replicasetsum(replicaset_depth) by instance
    servicesum(service_depth) by instance
    serviceaccountsum(serviceaccount_depth) by instance
    endpointsum(endpoint_depth) by instance
    daemonsetsum(daemonset_depth) by instance
    statefulsetsum(statefulset_depth) by instance
    replicationmanagersum(replicationmanager_depth) by instance
    Summary
    volumessum(volumes_depth)
    deploymentsum(deployment_depth)
    replicasetsum(replicaset_depth)
    servicesum(service_depth)
    serviceaccountsum(serviceaccount_depth)
    endpointsum(endpoint_depth)
    daemonsetsum(daemonset_depth)
    statefulsetsum(statefulset_depth)
    replicationmanagersum(replicationmanager_depth)

    Scheduler E2E Scheduling Latency​

    CatalogExpression
    Detailhistogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06
    Summarysum(histogram_quantile(0.99, sum(scheduler_e2e_scheduling_latency_microseconds_bucket) by (le, instance)) / 1e+06)

    Scheduler Preemption Attempts​

    CatalogExpression
    Detailsum(rate(scheduler_total_preemption_attempts[5m])) by (instance)
    Summarysum(rate(scheduler_total_preemption_attempts[5m]))

    Ingress Controller Connections​

    CatalogExpression
    Detail
    readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"}) by (instance)
    waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"}) by (instance)
    writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"}) by (instance)
    acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m]))) by (instance)
    activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m]))) by (instance)
    handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m]))) by (instance)
    Summary
    readingsum(nginx_ingress_controller_nginx_process_connections{state="reading"})
    waitingsum(nginx_ingress_controller_nginx_process_connections{state="waiting"})
    writingsum(nginx_ingress_controller_nginx_process_connections{state="writing"})
    acceptedsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="accepted"}[5m])))
    activesum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="active"}[5m])))
    handledsum(ceil(increase(nginx_ingress_controller_nginx_process_connections_total{state="handled"}[5m])))

    Ingress Controller Request Process Time​

    CatalogExpression
    Detailtopk(10, histogram_quantile(0.95,sum by (le, host, path)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))
    Summarytopk(10, histogram_quantile(0.95,sum by (le, host)(rate(nginx_ingress_controller_request_duration_seconds_bucket{host!="_"}[5m]))))

    Rancher Logging Metrics​

    Fluentd Buffer Queue Rate​

    CatalogExpression
    Detailsum(rate(fluentd_output_status_buffer_queue_length[5m])) by (instance)
    Summarysum(rate(fluentd_output_status_buffer_queue_length[5m]))

    Fluentd Input Rate​

    CatalogExpression
    Detailsum(rate(fluentd_input_status_num_records_total[5m])) by (instance)
    Summarysum(rate(fluentd_input_status_num_records_total[5m]))

    Fluentd Output Errors Rate​

    CatalogExpression
    Detailsum(rate(fluentd_output_status_num_errors[5m])) by (type)
    Summarysum(rate(fluentd_output_status_num_errors[5m]))

    Fluentd Output Rate​

    CatalogExpression
    Detailsum(rate(fluentd_output_status_num_records_total[5m])) by (instance)
    Summarysum(rate(fluentd_output_status_num_records_total[5m]))

    Workload Metrics​

    Workload CPU Utilization​

    CatalogExpression
    Detail
    cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    Summary
    cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

    Workload Memory Utilization​

    CatalogExpression
    Detailsum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""}) by (pod_name)
    Summarysum(container_memory_working_set_bytes{namespace="$namespace",pod_name=~"$podName", container_name!=""})

    Workload Network Packets​

    CatalogExpression
    Detail
    receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    Summary
    receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

    Workload Network I/O​

    CatalogExpression
    Detail
    receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    Summary
    receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

    Workload Disk I/O​

    CatalogExpression
    Detail
    readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m])) by (pod_name)
    Summary
    readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))
    writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name=~"$podName",container_name!=""}[5m]))

    Pod Metrics​

    Pod CPU Utilization​

    CatalogExpression
    Detail
    cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
    usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
    system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
    user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m])) by (container_name)
    Summary
    cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
    usage secondssum(rate(container_cpu_usage_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
    system secondssum(rate(container_cpu_system_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))
    user secondssum(rate(container_cpu_user_seconds_total{container_name!="POD",namespace="$namespace",pod_name="$podName", container_name!=""}[5m]))

    Pod Memory Utilization​

    CatalogExpression
    Detailsum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""}) by (container_name)
    Summarysum(container_memory_working_set_bytes{container_name!="POD",namespace="$namespace",pod_name="$podName",container_name!=""})

    Pod Network Packets​

    CatalogExpression
    Detail
    receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    Summary
    receive-packetssum(rate(container_network_receive_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    receive-droppedsum(rate(container_network_receive_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    receive-errorssum(rate(container_network_receive_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-packetssum(rate(container_network_transmit_packets_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-droppedsum(rate(container_network_transmit_packets_dropped_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmit-errorssum(rate(container_network_transmit_errors_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

    Pod Network I/O​

    CatalogExpression
    Detail
    receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    Summary
    receivesum(rate(container_network_receive_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    transmitsum(rate(container_network_transmit_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

    Pod Disk I/O​

    CatalogExpression
    Detail
    readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
    writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m])) by (container_name)
    Summary
    readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))
    writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name!=""}[5m]))

    Container Metrics​

    Container CPU Utilization​

    CatalogExpression
    cfs throttled secondssum(rate(container_cpu_cfs_throttled_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
    usage secondssum(rate(container_cpu_usage_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
    system secondssum(rate(container_cpu_system_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
    user secondssum(rate(container_cpu_user_seconds_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))

    Container Memory Utilization​

    sum(container_memory_working_set_bytes{namespace="$namespace",pod_name="$podName",container_name="$containerName"})

    Container Disk I/O​

    CatalogExpression
    readsum(rate(container_fs_reads_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
    writesum(rate(container_fs_writes_bytes_total{namespace="$namespace",pod_name="$podName",container_name="$containerName"}[5m]))
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html index 0402723f830..060c641f2ff 100644 --- a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html +++ b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/rbac-for-monitoring.html @@ -5,13 +5,13 @@ Role-based Access Control | Rancher Manager - +
    Version: v2.5

    Role-based Access Control

    This section describes the expectations for RBAC for Rancher Monitoring.

    Cluster Admins​

    By default, only those with the cluster-admin ClusterRole should be able to:

    • Install the rancher-monitoring App onto a cluster and all other relevant configuration performed on the chart deploy
      • e.g. whether default dashboards are created, what exporters are deployed onto the cluster to collect metrics, etc.
    • Create / modify / delete Prometheus deployments in the cluster via Prometheus CRs
    • Create / modify / delete Alertmanager deployments in the cluster via Alertmanager CRs
    • Persist new Grafana dashboards or datasources via creating ConfigMaps in the appropriate namespace
    • Expose certain Prometheus metrics to the k8s Custom Metrics API for HPA via a Secret in the cattle-monitoring-system namespace

    Users with Kubernetes ClusterRole-based Permissions​

    The rancher-monitoring chart installs the following three ClusterRoles. By default, they aggregate into the corresponding k8s ClusterRoles:

    ClusterRoleAggregates To Default K8s ClusterRole
    monitoring-adminadmin
    monitoring-editedit
    monitoring-viewview

    These ClusterRoles provide different levels of access to the Monitoring CRDs based on the actions that can be performed:

    CRDs (monitoring.coreos.com)AdminEditView
    • prometheuses
    • alertmanagers
    		Get, List, WatchGet, List, WatchGet, List, Watch
    • servicemonitors
    • podmonitors
    • prometheusrules
    		**Get, List, Watch

    On a high level, the following permissions are assigned by default as a result.

    Users with Kubernetes Admin/Edit Permissions​

    Only those with the the cluster-admin, admin or edit ClusterRole should be able to:

    • Modify the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs
    • Modify the alerting / recording rules of a Prometheus deployment via PrometheusRules CRs

    Users with Kubernetes View Permissions​

    Only those with who have some Kubernetes ClusterRole should be able to:

    • View the configuration of Prometheuses that are deployed within the cluster
    • View the configuration of Alertmanagers that are deployed within the cluster
    • View the scrape configuration of Prometheus deployments via ServiceMonitor and PodMonitor CRs
    • View the alerting/recording rules of a Prometheus deployment via PrometheusRules CRs

    Additional Monitoring Roles​

    Monitoring also creates additional Roles that are not assigned to users by default but are created within the cluster. They can be bound to a namespace by deploying a RoleBinding that references it. To define a RoleBinding with kubectl instead of through Rancher, click here.

    Admins should use these roles to provide more fine-grained access to users:

    RolePurpose
    monitoring-config-adminAllow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
    monitoring-config-editAllow admins to assign roles to users to be able to view / modify Secrets and ConfigMaps within the cattle-monitoring-system namespace. Modifying Secrets / ConfigMaps in this namespace could allow users to alter the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
    monitoring-config-viewAllow admins to assign roles to users to be able to view Secrets and ConfigMaps within the cattle-monitoring-system namespace. Viewing Secrets / ConfigMaps in this namespace could allow users to observe the cluster's Alertmanager configuration, Prometheus Adapter configuration, additional Grafana datasources, TLS secrets, etc.
    monitoring-dashboard-adminAllow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.
    monitoring-dashboard-editAllow admins to assign roles to users to be able to edit / view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.
    monitoring-dashboard-viewAllow admins to assign roles to users to be able to view ConfigMaps within the cattle-dashboards namespace. ConfigMaps in this namespace will correspond to Grafana Dashboards that are persisted onto the cluster.

    Additional Monitoring ClusterRoles​

    Monitoring also creates additional ClusterRoles that are not assigned to users by default but are created within the cluster. They are not aggregated by default but can be bound to a namespace by deploying a RoleBinding or ClusterRoleBinding that references it. To define a RoleBinding with kubectl instead of through Rancher, click here.

    RolePurpose
    monitoring-ui-viewAvailable as of Monitoring v2 14.5.100+ Provides read-only access to external Monitoring UIs by giving a user permission to list the Prometheus, Alertmanager, and Grafana endpoints and make GET requests to Prometheus, Grafana, and Alertmanager UIs through the Rancher proxy.

    Assigning Roles and ClusterRoles with kubectl​

    An alternative method to using Rancher to attach a Role or ClusterRole to a user or group is by defining bindings in YAML files that you create. You must first configure the RoleBinding with the YAML file, then you apply the config changes by running the kubectl apply command.

    • Roles: Below is an example of a YAML file to help you configure RoleBindings in Kubernetes to attach to a user. You will need to fill in the name below, and name is case-sensitive.
    # monitoring-config-view-role-binding.yaml
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: monitoring-config-view
      namespace: cattle-monitoring-system
    roleRef:
      kind: Role
      name: monitoring-config-view
      apiGroup: rbac.authorization.k8s.io
    subjects:
    - kind: User
      name: u-b4qkhsnliz # this can be found via `kubectl get users -A`
      apiGroup: rbac.authorization.k8s.io

    • kubectl: Below is an example of a kubectl command used to apply the binding you've created in the YAML file. As noted, you will need to fill in your YAML filename accordingly.

      • **kubectl apply -f monitoring-config-view-role-binding.yaml

    Users with Rancher Cluster Manager Based Permissions​

    The relationship between the default roles deployed by Rancher Cluster Manager (i.e. cluster-owner, cluster-member, project-owner, project-member), the default k8s roles, and the roles deployed by the rancher-monitoring chart are detailed in the table below:

    Default Rancher Permissions and Corresponding Kubernetes ClusterRoles
    Cluster Manager Rolek8s RoleMonitoring ClusterRole / RoleClusterRoleBinding or RoleBinding?
    cluster-ownercluster-adminN/AClusterRoleBinding
    cluster-memberadminmonitoring-adminClusterRoleBinding
    project-owneradminmonitoring-adminRoleBinding within Project namespace
    project-membereditmonitoring-editRoleBinding within Project namespace

    In addition to these default Roles, the following additional Rancher project roles can be applied to members of your Cluster to provide additional access to Monitoring. These Rancher Roles will be tied to ClusterRoles deployed by the Monitoring chart:

    Non-default Rancher Permissions and Corresponding Kubernetes ClusterRoles
    Cluster Manager RoleKubernetes ClusterRoleAvailable In Rancher FromAvailable in Monitoring v2 From
    View Monitoring*monitoring-ui-view2.4.8+9.4.204+

    * A User bound to the View Monitoring Rancher Role only has permissions to access external Monitoring UIs if provided links to those UIs. In order to access the Monitoring Pane on Cluster Explorer to get those links, the User must be a Project Member of at least one Project.

    Differences in 2.5.x​

    Users with the project-member or project-owners roles assigned will not be given access to either Prometheus or Grafana in Rancher 2.5.x since we only create Grafana or Prometheus on a cluster-level.

    In addition, while project owners will still be only able to add ServiceMonitors / PodMonitors that scrape resources within their project's namespace by default, PrometheusRules are not scoped to a single namespace / project. Therefore, any alert rules or recording rules created by project-owners within their project namespace will be applied across the entire cluster, although they will be unable to view / edit / delete any rules that were created outside the project's namespace.

    Assigning Additional Access​

    If cluster-admins would like to provide additional admin/edit access to users outside of the roles offered by the rancher-monitoring chart, the following table identifies the potential impact:

    CRDs (monitoring.coreos.com)Can it cause impact outside of a namespace / project?Impact
    prometheusesYes, this resource can scrape metrics from any targets across the entire cluster (unless the Operator itself is otherwise configured).User will be able to define the configuration of new cluster-level Prometheus deployments that should be created in the cluster.
    alertmanagersNoUser will be able to define the configuration of new cluster-level Alertmanager deployments that should be created in the cluster. Note: if you just want to allow users to configure settings like Routes and Receivers, you should just provide access to the Alertmanager Config Secret instead.
    • servicemonitors
    • podmonitors
    		No, not by default; this is configurable via ignoreNamespaceSelectors on the Prometheus CR.User will be able to set up scrapes by Prometheus on endpoints exposed by Services / Pods within the namespace they are given this permission in.
    prometheusrulesYes, PrometheusRules are cluster-scoped.User will be able to define alert or recording rules on Prometheus based on any series collected across the entire cluster.
    k8s ResourcesNamespaceCan it cause impact outside of a namespace / project?Impact
    • secrets
    • configmaps
    		cattle-monitoring-systemYes, Configs and Secrets in this namespace can impact the entire monitoring / alerting pipeline.User will be able to create or edit Secrets / ConfigMaps such as the Alertmanager Config, Prometheus Adapter Config, TLS secrets, additional Grafana datasources, etc. This can have broad impact on all cluster monitoring / alerting.
    • secrets
    • configmaps
    		cattle-dashboardsYes, Configs and Secrets in this namespace can create dashboards that make queries on all metrics collected at a cluster-level.User will be able to create Secrets / ConfigMaps that persist new Grafana Dashboards only.

    Role-based Access Control for Grafana​

    Rancher allows any users who are authenticated by Kubernetes and have access the Grafana service deployed by the Rancher Monitoring chart to access Grafana via the Rancher Dashboard UI. By default, all users who are able to access Grafana are given the Viewer role, which allows them to view any of the default dashboards deployed by Rancher.

    However, users can choose to log in to Grafana as an Admin if necessary. The default Admin username and password for the Grafana instance will be admin/prom-operator, but alternative credentials can also be supplied on deploying or upgrading the chart.

    To see the Grafana UI, install rancher-monitoring. Then go to the Cluster Explorer. In the top left corner, click Cluster Explorer > Monitoring. Then click **Grafana.

    Cluster Compute Resources Dashboard in Grafana

    Cluster Compute Resources Dashboard in Grafana

    Default Dashboards in Grafana

    Default Dashboards in Grafana

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html index 1669edd8da6..cff31b7b6b8 100644 --- a/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html +++ b/v2.5/explanations/integrations-in-rancher/monitoring-and-alerting/windows-support.html @@ -5,13 +5,13 @@ Windows Cluster Support for Monitoring V2 | Rancher Manager - +
    Version: v2.5

    Windows Cluster Support for Monitoring V2

    Available as of v2.5.8

    Starting at Monitoring V2 14.5.100 (used by default in Rancher 2.5.8), Monitoring V2 can now be deployed on a Windows cluster and will scrape metrics from Windows nodes using prometheus-community/windows_exporter (previously named wmi_exporter).

    Comparison to Monitoring V1​

    Unlike Monitoring V1 for Windows, metrics collected by windows_exporter will be labeled as windows_ instead of wmi_ in accordance to a naming change from upstream from wmi_exporter to windows_exporter.

    In addition, Monitoring V2 for Windows will no longer require users to keep port 9796 open on Windows hosts since the host metrics will published directly onto a port exposed on the windows-exporter Pod. This feature was powered by recent changes made by wins v0.1.0 to support publishing ports exposed on the hostNetwork on Pods that use wins to run a privileged Windows binary as a host process.

    Cluster Requirements​

    Monitoring V2 for Windows can only scrape metrics from Windows hosts that have a minimum wins version of v0.1.0. To be able to fully deploy Monitoring V2 for Windows, all of your hosts must meet this requirement.

    If you provision a fresh RKE1 cluster in Rancher 2.5.8, your cluster should already meet this requirement.

    Upgrading Existing Clusters to wins v0.1.0​

    If the cluster was provisioned before Rancher 2.5.8 (even if the current Rancher version is 2.5.8), you will not be able to successfully deploy Monitoring V2 for Windows until you upgrade the wins version on each host to at least v0.1.0.

    To facilitate this upgrade, Rancher 2.5.8 has released a brand new Helm chart called rancher-wins-upgrader.

    Prerequisite: Make sure Monitoring V1 for Windows is uninstalled.

    1. Deploy rancher-wins-upgrader with the following override:
      # Masquerading bootstraps the wins-upgrader installation via
      # a previously whitelisted process path since the normal install path,
      # c:\etc\rancher\wins\wins-upgrade.exe is not normally whitelisted.
      # In this case, we are using the previously whitelisted process
      # path used by Monitoring V1.
      masquerade:
        enabled: true
        as: c:\\etc\wmi-exporter\wmi-exporter.exe

      Note for Non-Default Windows Prefix Path: If you set up the RKE cluster with a cluster.yml that has a non-default win_prefix_path, you will need to update the masquerade.as field with your prefix path in place of c:\\.

      For example, if you have win_prefix_path: 'c:\host\opt\', then you will need to set as: c:\host\opt\etc\wmi-exporter\wmi-exporter.exe.

    2. Once all your hosts have been successfully upgraded, please ensure that you deploy the Helm chart once again with default values to avoid conflicts with the following settings:
      masquerade:
        enabled: false

    Result: The hosts are ready for Monitoring V2 to be installed. You may choose to uninstall the rancher-wins-upgrader chart or keep it in your cluster to facilitate future upgrades.

    For more information on how it can be used, please see the README.md of the chart.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/explanations/integrations-in-rancher/opa-gatekeeper.html b/v2.5/explanations/integrations-in-rancher/opa-gatekeeper.html index ab1325ef3ce..7b3988ae281 100644 --- a/v2.5/explanations/integrations-in-rancher/opa-gatekeeper.html +++ b/v2.5/explanations/integrations-in-rancher/opa-gatekeeper.html @@ -5,13 +5,13 @@ OPA Gatekeeper | Rancher Manager - +
    Version: v2.5

    OPA Gatekeeper

    To ensure consistency and compliance, every organization needs the ability to define and enforce policies in its environment in an automated way. OPA (Open Policy Agent) is a policy engine that facilitates policy-based control for cloud native environments. Rancher provides the ability to enable OPA Gatekeeper in Kubernetes clusters, and also installs a couple of built-in policy definitions, which are also called constraint templates.

    OPA provides a high-level declarative language that lets you specify policy as code and ability to extend simple APIs to offload policy decision-making.

    OPA Gatekeeper is a project that provides integration between OPA and Kubernetes. OPA Gatekeeper provides:

    • An extensible, parameterized policy library.
    • Native Kubernetes CRDs for instantiating the policy library, also called “constraints."
    • Native Kubernetes CRDs for extending the policy library, also called "constraint templates."
    • Audit functionality.

    To read more about OPA, please refer to the official documentation.

    How the OPA Gatekeeper Integration Works​

    Kubernetes provides the ability to extend API server functionality via admission controller webhooks, which are invoked whenever a resource is created, updated or deleted. Gatekeeper is installed as a validating webhook and enforces policies defined by Kubernetes custom resource definitions. In addition to the admission control usage, Gatekeeper provides the capability to audit existing resources in Kubernetes clusters and mark current violations of enabled policies.

    OPA Gatekeeper is made available via Rancher's Helm system chart, and it is installed in a namespace named gatekeeper-system.

    Enabling OPA Gatekeeper in a Cluster​

    In Rancher v2.5, the OPA Gatekeeper application was improved. The Rancher v2.4 feature can't be upgraded to the new version in Rancher v2.5. If you installed OPA Gatekeeper in Rancher v2.4, you will need to uninstall OPA Gatekeeper and its CRDs from the old UI, then reinstall it in Rancher v2.5. To uninstall the CRDs run the following command in the kubectl console kubectl delete crd configs.config.gatekeeper.sh constrainttemplates.templates.gatekeeper.sh.

    Prerequisite: Only administrators and cluster owners can enable OPA Gatekeeper.

    OPA Gatekeeper can be installed from the new Cluster Explorer view in Rancher v2.5, or from the cluster manager view.

    Enabling OPA Gatekeeper from Cluster Explorer​

    1. Go to the cluster view in the Rancher UI. Click Cluster Explorer.
    2. Click Apps in the top navigation bar.
    3. Click rancher-gatekeeper.
    4. Click Install.

    Result: OPA Gatekeeper is deployed in your Kubernetes cluster.

    Enabling OPA Gatekeeper from the Cluster Manager View​

    1. Go to the cluster view in the Rancher UI.
    2. Click Tools > OPA Gatekeeper.
    3. Click Install.

    Result: OPA Gatekeeper is deployed in your Kubernetes cluster.

    Constraint Templates​

    Constraint templates are Kubernetes custom resources that define the schema and Rego logic of the OPA policy to be applied by Gatekeeper. For more information on the Rego policy language, refer to the official documentation.

    When OPA Gatekeeper is enabled, Rancher installs some templates by default.

    To list the constraint templates installed in the cluster, go to the left side menu under OPA Gatekeeper and click on Templates.

    Rancher also provides the ability to create your own constraint templates by importing YAML definitions.

    Creating and Configuring Constraints​

    Constraints are Kubernetes custom resources that define the scope of objects to which a specific constraint template applies to. The complete policy is defined by constraint templates and constraints together.

    Prerequisites: OPA Gatekeeper must be enabled in the cluster.

    To list the constraints installed, go to the left side menu under OPA Gatekeeper, and click on Constraints.

    New constraints can be created from a constraint template.

    Rancher provides the ability to create a constraint by using a convenient form that lets you input the various constraint fields.

    The Edit as yaml option is also available to configure the the constraint's yaml definition.

    Exempting Rancher's System Namespaces from Constraints​

    When a constraint is created, ensure that it does not apply to any Rancher or Kubernetes system namespaces. If the system namespaces are not excluded, then it is possible to see many resources under them marked as violations of the constraint.

    To limit the scope of the constraint only to user namespaces, always specify these namespaces under the Match field of the constraint.

    Also, the constraint may interfere with other Rancher functionality and deny system workloads from being deployed. To avoid this, exclude all Rancher-specific namespaces from your constraints.

    Enforcing Constraints in your Cluster​

    When the Enforcement Action is Deny, the constraint is immediately enabled and will deny any requests that violate the policy defined. By default, the enforcement value is Deny.

    When the Enforcement Action is Dryrun, then any resources that violate the policy are only recorded under the constraint's status field.

    To enforce constraints, create a constraint using the form. In the Enforcement Action field, choose Deny.

    Audit and Violations in your Cluster​

    OPA Gatekeeper runs a periodic audit to check if any existing resource violates any enforced constraint. The audit-interval (default 300s) can be configured while installing Gatekeeper.

    On the Gatekeeper page, any violations of the defined constraints are listed.

    Also under Constraints, the number of violations of the constraint can be found.

    The detail view of each constraint lists information about the resource that violated the constraint.

    Disabling Gatekeeper​

    1. Navigate to the cluster's Dashboard view
    2. On the left side menu, expand the cluster menu and click on OPA Gatekeeper.
    3. Click the ⋮ > Disable.

    Result: Upon disabling OPA Gatekeeper, all constraint templates and constraints will also be deleted.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq.html b/v2.5/faq.html index 72ede605419..2e1311db5e4 100644 --- a/v2.5/faq.html +++ b/v2.5/faq.html @@ -5,13 +5,13 @@ FAQ | Rancher Manager - +
    Version: v2.5

    FAQ

    This FAQ is a work in progress designed to answer the questions our users most frequently ask about Rancher v2.x.

    See Technical FAQ, for frequently asked technical questions.


    Does Rancher v2.x support Docker Swarm and Mesos as environment types?

    When creating an environment in Rancher v2.x, Swarm and Mesos will no longer be standard options you can select. However, both Swarm and Mesos will continue to be available as Catalog applications you can deploy. It was a tough decision to make but, in the end, it came down to adoption. For example, out of more than 15,000 clusters, only about 200 or so are running Swarm.


    Is it possible to manage Azure Kubernetes Services with Rancher v2.x?

    Yes.


    Does Rancher support Windows?

    As of Rancher 2.3.0, we support Windows Server 1809 containers. For details on how to set up a cluster with Windows worker nodes, refer to the section on configuring custom clusters for Windows.


    Does Rancher support Istio?

    As of Rancher 2.3.0, we support Istio.

    Furthermore, Istio is implemented in our micro-PaaS "Rio", which works on Rancher 2.x along with any CNCF compliant Kubernetes cluster. You can read more about it here


    Will Rancher v2.x support Hashicorp's Vault for storing secrets?

    There is no built-in integration of Rancher and Hashicorp's Vault. Rancher manages Kubernetes and integrates with secrets via the Kubernetes API. Thus in any downstream (managed) cluster, you can use a secret vault of your choice provided it integrates with Kubernetes, including Vault.


    Does Rancher v2.x support RKT containers as well?

    At this time, we only support Docker.


    Does Rancher v2.x support Calico, Contiv, Contrail, Flannel, Weave net, etc., for embedded and registered Kubernetes?

    Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico and Weave. Always refer to the Rancher Support Matrix for details about what is officially supported.


    Are you planning on supporting Traefik for existing setups?

    We don't currently plan on providing embedded Traefik support, but we're still exploring load-balancing approaches.


    Can I import OpenShift Kubernetes clusters into v2.x?

    Our goal is to run any upstream Kubernetes clusters. Therefore, Rancher v2.x should work with OpenShift, but we haven't tested it yet.


    Are you going to integrate Longhorn?

    Yes. Longhorn was integrated into Rancher v2.5+.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/container-network-interface-providers.html b/v2.5/faq/container-network-interface-providers.html index 7cd3e7d0934..c6e1758ab49 100644 --- a/v2.5/faq/container-network-interface-providers.html +++ b/v2.5/faq/container-network-interface-providers.html @@ -5,13 +5,13 @@ Container Network Interface (CNI) Providers | Rancher Manager - +
    Version: v2.5

    Container Network Interface (CNI) Providers

    What is CNI?​

    CNI (Container Network Interface), a Cloud Native Computing Foundation project, consists of a specification and libraries for writing plugins to configure network interfaces in Linux containers, along with a number of plugins. CNI concerns itself only with network connectivity of containers and removing allocated resources when the container is deleted.

    Kubernetes uses CNI as an interface between network providers and Kubernetes pod networking.

    CNI Logo

    For more information visit CNI GitHub project.

    What Network Models are Used in CNI?​

    CNI network providers implement their network fabric using either an encapsulated network model such as Virtual Extensible Lan (VXLAN) or an unencapsulated network model such as Border Gateway Protocol (BGP).

    What is an Encapsulated Network?​

    This network model provides a logical Layer 2 (L2) network encapsulated over the existing Layer 3 (L3) network topology that spans the Kubernetes cluster nodes. With this model you have an isolated L2 network for containers without needing routing distribution, all at the cost of minimal overhead in terms of processing and increased IP package size, which comes from an IP header generated by overlay encapsulation. Encapsulation information is distributed by UDP ports between Kubernetes workers, interchanging network control plane information about how MAC addresses can be reached. Common encapsulation used in this kind of network model is VXLAN, Internet Protocol Security (IPSec), and IP-in-IP.

    In simple terms, this network model generates a kind of network bridge extended between Kubernetes workers, where pods are connected.

    This network model is used when an extended L2 bridge is preferred. This network model is sensitive to L3 network latencies of the Kubernetes workers. If datacenters are in distinct geolocations, be sure to have low latencies between them to avoid eventual network segmentation.

    CNI network providers using this network model include Flannel, Canal, and Weave.

    Encapsulated Network

    What is an Unencapsulated Network?​

    This network model provides an L3 network to route packets between containers. This model doesn't generate an isolated l2 network, nor generates overhead. These benefits come at the cost of Kubernetes workers having to manage any route distribution that's needed. Instead of using IP headers for encapsulation, this network model uses a network protocol between Kubernetes workers to distribute routing information to reach pods, such as BGP.

    In simple terms, this network model generates a kind of network router extended between Kubernetes workers, which provides information about how to reach pods.

    This network model is used when a routed L3 network is preferred. This mode dynamically updates routes at the OS level for Kubernetes workers. It's less sensitive to latency.

    CNI network providers using this network model include Calico and Romana.

    Unencapsulated Network

    What CNI Providers are Provided by Rancher?​

    Out-of-the-box, Rancher provides the following CNI network providers for Kubernetes clusters: Canal, Flannel, Calico, and Weave. You can choose your CNI network provider when you create new Kubernetes clusters from Rancher.

    Canal​

    Canal Logo

    Canal is a CNI network provider that gives you the best of Flannel and Calico. It allows users to easily deploy Calico and Flannel networking together as a unified networking solution, combining Calico’s network policy enforcement with the rich superset of Calico (unencapsulated) and/or Flannel (encapsulated) network connectivity options.

    In Rancher, Canal is the default CNI network provider combined with Flannel and VXLAN encapsulation.

    Kubernetes workers should open UDP port 8472 (VXLAN) and TCP port 9099 (healthcheck). For details, refer to the port requirements for user clusters.

    For more information, see the Canal GitHub Page.

    Flannel​

    Flannel Logo

    Flannel is a simple and easy way to configure L3 network fabric designed for Kubernetes. Flannel runs a single binary agent named flanneld on each host, which is responsible for allocating a subnet lease to each host out of a larger, preconfigured address space. Flannel uses either the Kubernetes API or etcd directly to store the network configuration, the allocated subnets, and any auxiliary data (such as the host's public IP). Packets are forwarded using one of several backend mechanisms, with the default encapsulation being VXLAN.

    Encapsulated traffic is unencrypted by default. Therefore, flannel provides an experimental backend for encryption, IPSec, which makes use of strongSwan to establish encrypted IPSec tunnels between Kubernetes workers.

    Kubernetes workers should open UDP port 8472 (VXLAN) and TCP port 9099 (healthcheck). See the port requirements for user clusters for more details.

    Flannel Diagram

    For more information, see the Flannel GitHub Page.

    Calico​

    Calico Logo

    Calico enables networking and network policy in Kubernetes clusters across the cloud. Calico uses a pure, unencapsulated IP network fabric and policy engine to provide networking for your Kubernetes workloads. Workloads are able to communicate over both cloud infrastructure and on-prem using BGP.

    Calico also provides a stateless IP-in-IP encapsulation mode that can be used, if necessary. Calico also offers policy isolation, allowing you to secure and govern your Kubernetes workloads using advanced ingress and egress policies.

    Kubernetes workers should open TCP port 179 (BGP). See the port requirements for user clusters for more details.

    Calico Diagram

    For more information, see the following pages:

    Weave​

    Weave Logo

    Weave enables networking and network policy in Kubernetes clusters across the cloud. Additionally, it support encrypting traffic between the peers.

    Kubernetes workers should open TCP port 6783 (control port), UDP port 6783 and UDP port 6784 (data ports). See the port requirements for user clusters for more details.

    For more information, see the following pages:

    CNI Features by Provider​

    The following table summarizes the different features available for each CNI network provider provided by Rancher.

    ProviderNetwork ModelRoute DistributionNetwork PoliciesMeshExternal DatastoreEncryptionIngress/Egress Policies
    CanalEncapsulated (VXLAN)NoYesNoK8S APINoYes
    FlannelEncapsulated (VXLAN)NoNoNoK8S APINoNo
    CalicoEncapsulated (VXLAN,IPIP) OR UnencapsulatedYesYesYesEtcd and K8S APINoYes
    WeaveEncapsulatedYesYesYesNoYesYes

    • Network Model: Encapsulated or unencapsulated. For more information, see What Network Models are Used in CNI?

    • Route Distribution: An exterior gateway protocol designed to exchange routing and reachability information on the Internet. BGP can assist with pod-to-pod networking between clusters. This feature is a must on unencapsulated CNI network providers, and it is typically done by BGP. If you plan to build clusters split across network segments, route distribution is a feature that's nice-to-have.

    • Network Policies: Kubernetes offers functionality to enforce rules about which services can communicate with each other using network policies. This feature is stable as of Kubernetes v1.7 and is ready to use with certain networking plugins.

    • Mesh: This feature allows service-to-service networking communication between distinct Kubernetes clusters.

    • External Datastore: CNI network providers with this feature need an external datastore for its data.

    • Encryption: This feature allows cyphered and secure network control and data planes.

    • Ingress/Egress Policies: This feature allows you to manage routing control for both Kubernetes and non-Kubernetes communications.

    CNI Community Popularity​

    The following table summarizes different GitHub metrics to give you an idea of each project's popularity and activity. This data was collected in January 2020.

    ProviderProjectStarsForksContributors
    Canalhttps://github.com/projectcalico/canal6148919
    flannelhttps://github.com/coreos/flannel49771.4k140
    Calicohttps://github.com/projectcalico/calico1534429135
    Weavehttps://github.com/weaveworks/weave/573755973

    Which CNI Provider Should I Use?​

    It depends on your project needs. There are many different providers, which each have various features and options. There isn't one provider that meets everyone's needs.

    Canal is the default CNI network provider. We recommend it for most use cases. It provides encapsulated networking for containers with Flannel, while adding Calico network policies that can provide project/namespace isolation in terms of networking.

    How can I configure a CNI network provider?​

    Please see Cluster Options on how to configure a network provider for your cluster. For more advanced configuration options, please see how to configure your cluster using a Config File and the options for Network Plug-ins.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/deprecated-features-in-v2.5.html b/v2.5/faq/deprecated-features-in-v2.5.html index 5b4a2ad4f35..3424151b940 100644 --- a/v2.5/faq/deprecated-features-in-v2.5.html +++ b/v2.5/faq/deprecated-features-in-v2.5.html @@ -5,13 +5,13 @@ Deprecated Features in Rancher v2.5 | Rancher Manager - +
    Version: v2.5

    Deprecated Features in Rancher v2.5

    What is Rancher's Deprecation policy?​

    Starting in Rancher 2.5 we have published our official deprecation policy in the support terms of service.

    Where can I find out which features have been deprecated in Rancher 2.5?​

    Rancher will publish deprecated features as part of the release notes for Rancher found on GitHub.

    What can I expect when a feature is marked for deprecation?​

    In the release where functionality is marked as Deprecated it will still be available and supported allowing upgrades to follow the usual procedure. Once upgraded, users/admins should start planning to move away from the deprecated functionality before upgrading to the release it marked as removed. The recommendation for new deployments is to not use the deprecated feature.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/install-and-configure-kubectl.html b/v2.5/faq/install-and-configure-kubectl.html index 9974035547f..1470ab08264 100644 --- a/v2.5/faq/install-and-configure-kubectl.html +++ b/v2.5/faq/install-and-configure-kubectl.html @@ -5,13 +5,13 @@ Installing and Configuring kubectl | Rancher Manager - +
    Version: v2.5

    Installing and Configuring kubectl

    kubectl is a CLI utility for running commands against Kubernetes clusters. It's required for many maintenance and administrative tasks in Rancher 2.x.

    Installation​

    See kubectl Installation for installation on your operating system.

    Configuration​

    When you create a Kubernetes cluster with RKE, RKE creates a kube_config_cluster.yml in the local directory that contains credentials to connect to your new cluster with tools like kubectl or helm.

    You can copy this file to $HOME/.kube/config or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_cluster.yml.

    export KUBECONFIG=$(pwd)/kube_config_cluster.yml

    Test your connectivity with kubectl and see if you can get the list of nodes back.

    kubectl get nodes
     NAME                          STATUS    ROLES                      AGE       VERSION
    165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.10.1
    165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.10.1
    165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.10.1
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/networking.html b/v2.5/faq/networking.html index b1b5364ce69..a44b5df5ade 100644 --- a/v2.5/faq/networking.html +++ b/v2.5/faq/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/rancher-is-no-longer-needed.html b/v2.5/faq/rancher-is-no-longer-needed.html index 2c04e026678..e459f84f3c9 100644 --- a/v2.5/faq/rancher-is-no-longer-needed.html +++ b/v2.5/faq/rancher-is-no-longer-needed.html @@ -5,13 +5,13 @@ Rancher is No Longer Needed | Rancher Manager - +
    Version: v2.5

    Rancher is No Longer Needed

    This page is intended to answer questions about what happens if you don't want Rancher anymore, if you don't want a cluster to be managed by Rancher anymore, or if the Rancher server is deleted.

    If the Rancher server is deleted, what happens to the workloads in my downstream clusters?​

    If Rancher is ever deleted or unrecoverable, all workloads in the downstream Kubernetes clusters managed by Rancher will continue to function as normal.

    If the Rancher server is deleted, how do I access my downstream clusters?​

    The capability to access a downstream cluster without Rancher depends on the type of cluster and the way that the cluster was created. To summarize:

    • Registered clusters: The cluster will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher.
    • Hosted Kubernetes clusters: If you created the cluster in a cloud-hosted Kubernetes provider such as EKS, GKE, or AKS, you can continue to manage the cluster using your provider's cloud credentials.
    • RKE clusters: Please note that you will no longer be able to manage the individual Kubernetes components or perform any upgrades on them after the deletion of the Rancher server. However, you can still access the cluster to manage your workloads. To access an RKE cluster, the cluster must have the authorized cluster endpoint enabled, and you must have already downloaded the cluster's kubeconfig file from the Rancher UI. (The authorized cluster endpoint is enabled by default for RKE clusters.) With this endpoint, you can access your cluster with kubectl directly instead of communicating through the Rancher server's authentication proxy. For instructions on how to configure kubectl to use the authorized cluster endpoint, refer to the section about directly accessing clusters with kubectl and the kubeconfig file. These clusters will use a snapshot of the authentication as it was configured when Rancher was removed.

    What if I don't want Rancher anymore?​

    If you installed Rancher on a Kubernetes cluster, remove Rancher by using the System Tools with the remove subcommand.

    As of Rancher v2.5.8, uninstalling Rancher in high-availability (HA) mode will also remove all helm-operation-* pods and the following apps:

    • fleet
    • fleet-agent
    • rancher-operator
    • rancher-webhook

    Custom resources (CRDs) and custom namespaces will still need to be manually removed.

    If you installed Rancher with Docker, you can uninstall Rancher by removing the single Docker container that it runs in.

    Imported clusters will not be affected by Rancher being removed. For other types of clusters, refer to the section on accessing downstream clusters when Rancher is removed.

    What if I don't want my registered cluster managed by Rancher?​

    If a registered cluster is deleted from the Rancher UI, the cluster is detached from Rancher, leaving it intact and accessible by the same methods that were used to access it before it was registered in Rancher.

    To detach the cluster,

    1. From the Global view in Rancher, go to the Clusters tab.
    2. Go to the registered cluster that should be detached from Rancher and click ⋮ > Delete.
    3. Click Delete.

    Result: The registered cluster is detached from Rancher and functions normally outside of Rancher.

    What if I don't want my RKE cluster or hosted Kubernetes cluster managed by Rancher?​

    At this time, there is no functionality to detach these clusters from Rancher. In this context, "detach" is defined as the ability to remove Rancher components from the cluster and manage access to the cluster independently of Rancher.

    The capability to manage these clusters without Rancher is being tracked in this issue.

    For information about how to access clusters if the Rancher server is deleted, refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/security.html b/v2.5/faq/security.html index e78bc3fcee5..d654e6bbda8 100644 --- a/v2.5/faq/security.html +++ b/v2.5/faq/security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
    Version: v2.5

    Security

    Is there a Hardening Guide?

    The Hardening Guide is now located in the main Security section.


    What are the results of Rancher's Kubernetes cluster when it is CIS benchmarked?

    We have run the CIS Kubernetes benchmark against a hardened Rancher Kubernetes cluster. The results of that assessment can be found in the main Security section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/technical-items.html b/v2.5/faq/technical-items.html index 5accf88cbb2..02261250c11 100644 --- a/v2.5/faq/technical-items.html +++ b/v2.5/faq/technical-items.html @@ -5,13 +5,13 @@ Technical | Rancher Manager - +
    Version: v2.5

    Technical

    How can I reset the administrator password?​

    Docker Install:

    $ docker exec -ti <container_id> reset-password
    New password for default administrator (user-xxxxx):
    <new_password>

    Kubernetes install (Helm):

    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- reset-password
    New password for default administrator (user-xxxxx):
    <new_password>

    I deleted/deactivated the last admin, how can I fix it?​

    Docker Install:

    $ docker exec -ti <container_id> ensure-default-admin
    New default administrator (user-xxxxx)
    New password for default administrator (user-xxxxx):
    <new_password>

    Kubernetes install (Helm):

    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin
    New password for default administrator (user-xxxxx):
    <new_password>

    How can I enable debug logging?​

    See Troubleshooting: Logging

    My ClusterIP does not respond to ping​

    ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using curl to access the IP and port to see if it responds.

    Where can I manage Node Templates?​

    Node Templates can be accessed by opening your account menu (top right) and selecting Node Templates.

    Why is my Layer-4 Load Balancer in Pending state?​

    The Layer-4 Load Balancer is created as type: LoadBalancer. In Kubernetes, this needs a cloud provider or controller that can satisfy these requests, otherwise these will be in Pending state forever. More information can be found on Cloud Providers or Create External Load Balancer

    Where is the state of Rancher stored?​

    • Docker Install: in the embedded etcd of the rancher/rancher container, located at /var/lib/rancher.
    • Kubernetes install: in the etcd of the RKE cluster created to run Rancher.

    How are the supported Docker versions determined?​

    We follow the validated Docker versions for upstream Kubernetes releases. The validated versions can be found under External Dependencies in the Kubernetes release CHANGELOG.md.

    How can I access nodes created by Rancher?​

    SSH keys to access the nodes created by Rancher can be downloaded via the Nodes view. Choose the node which you want to access and click on the vertical ⋮ button at the end of the row, and choose Download Keys as shown in the picture below.

    Download Keys

    Unzip the downloaded zip file, and use the file id_rsa to connect to you host. Be sure to use the correct username (rancher or docker for RancherOS, ubuntu for Ubuntu, ec2-user for Amazon Linux)

    $ ssh -i id_rsa user@ip_of_node

    How can I automate task X in Rancher?​

    The UI consists of static files, and works based on responses of the API. That means every action/task that you can execute in the UI, can be automated via the API. There are 2 ways to do this:

    • Visit https://your_rancher_ip/v3 and browse the API options.
    • Capture the API calls when using the UI (Most commonly used for this is Chrome Developer Tools but you can use anything you like)

    The IP address of a node changed, how can I recover?​

    A node is required to have a static IP configured (or a reserved IP via DHCP). If the IP of a node has changed, you will have to remove it from the cluster and readd it. After it is removed, Rancher will update the cluster to the correct state. If the cluster is no longer in Provisioning state, the node is removed from the cluster.

    When the IP address of the node changed, Rancher lost connection to the node, so it will be unable to clean the node properly. See Cleaning cluster nodes to clean the node.

    When the node is removed from the cluster, and the node is cleaned, you can readd the node to the cluster.

    How can I add additional arguments/binds/environment variables to Kubernetes components in a Rancher Launched Kubernetes cluster?​

    You can add additional arguments/binds/environment variables via the Config File option in Cluster Options. For more information, see the Extra Args, Extra Binds, and Extra Environment Variables in the RKE documentation or browse the Example Cluster.ymls.

    How do I check if my certificate chain is valid?​

    Use the openssl verify command to validate your certificate chain:

    Note: Configure SSL_CERT_DIR and SSL_CERT_FILE to a dummy location to make sure the OS installed certificates are not used when verifying manually.

    SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem rancher.yourdomain.com.pem
    rancher.yourdomain.com.pem: OK

    If you receive the error unable to get local issuer certificate, the chain is incomplete. This usually means that there is an intermediate CA certificate that issued your server certificate. If you already have this certificate, you can use it in the verification of the certificate like shown below:

    SSL_CERT_DIR=/dummy SSL_CERT_FILE=/dummy openssl verify -CAfile ca.pem -untrusted intermediate.pem rancher.yourdomain.com.pem
    rancher.yourdomain.com.pem: OK

    If you have successfully verified your certificate chain, you should include needed intermediate CA certificates in the server certificate to complete the certificate chain for any connection made to Rancher (for example, by the Rancher agent). The order of the certificates in the server certificate file should be first the server certificate itself (contents of rancher.yourdomain.com.pem), followed by intermediate CA certificate(s) (contents of intermediate.pem).

    -----BEGIN CERTIFICATE-----
    %YOUR_CERTIFICATE%
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    %YOUR_INTERMEDIATE_CERTIFICATE%
    -----END CERTIFICATE-----

    If you still get errors during verification, you can retrieve the subject and the issuer of the server certificate using the following command:

    openssl x509 -noout -subject -issuer -in rancher.yourdomain.com.pem
    subject= /C=GB/ST=England/O=Alice Ltd/CN=rancher.yourdomain.com
    issuer= /C=GB/ST=England/O=Alice Ltd/CN=Alice Intermediate CA

    How do I check Common Name and Subject Alternative Names in my server certificate?​

    Although technically an entry in Subject Alternative Names is required, having the hostname in both Common Name and as entry in Subject Alternative Names gives you maximum compatibility with older browser/applications.

    Check Common Name:

    openssl x509 -noout -subject -in cert.pem
    subject= /CN=rancher.my.org

    Check Subject Alternative Names:

    openssl x509 -noout -in cert.pem -text | grep DNS
                    DNS:rancher.my.org

    Why does it take 5+ minutes for a pod to be rescheduled when a node has failed?​

    This is due to a combination of the following default Kubernetes settings:

    • kubelet
      • node-status-update-frequency: Specifies how often kubelet posts node status to master (default 10s)
    • kube-controller-manager
      • node-monitor-period: The period for syncing NodeStatus in NodeController (default 5s)
      • node-monitor-grace-period: Amount of time which we allow running Node to be unresponsive before marking it unhealthy (default 40s)
      • pod-eviction-timeout: The grace period for deleting pods on failed nodes (default 5m0s)

    See Kubernetes: kubelet and Kubernetes: kube-controller-manager for more information on these settings.

    In Kubernetes v1.13, the TaintBasedEvictions feature is enabled by default. See Kubernetes: Taint based Evictions for more information.

    • kube-apiserver (Kubernetes v1.13 and up)
      • default-not-ready-toleration-seconds: Indicates the tolerationSeconds of the toleration for notReady:NoExecute that is added by default to every pod that does not already have such a toleration.
      • default-unreachable-toleration-seconds: Indicates the tolerationSeconds of the toleration for unreachable:NoExecute that is added by default to every pod that does not already have such a toleration.

    Can I use keyboard shortcuts in the UI?​

    Yes, most parts of the UI can be reached using keyboard shortcuts. For an overview of the available shortcuts, press ? anywhere in the UI.

    What does Unknown schema for type: errors followed by something like catalog.cattle.io.operation mean when trying to modify an App?​

    This error occurs when Kubernetes can not find the CRD mentioned. The vast majority of the time these are a result of missing RBAC permissions. Try with an admin user and if this works, add permissions for the resource mentioned by the error (ie. Get, List, Patch as needed).

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/faq/telemetry.html b/v2.5/faq/telemetry.html index 26ac31d78e0..3b5728c8c97 100644 --- a/v2.5/faq/telemetry.html +++ b/v2.5/faq/telemetry.html @@ -5,13 +5,13 @@ Telemetry | Rancher Manager - +
    Version: v2.5

    Telemetry

    What is Telemetry?​

    Telemetry collects aggregate information about the size of Rancher installations, versions of components used, and which features are used. This information is used by Rancher Labs to help make the product better and is not shared with third-parties.

    What information is collected?​

    No specific identifying information like usernames, passwords, or the names or addresses of user resources will ever be collected.

    The primary things collected include:

    • Aggregate counts (smallest, average, largest, total) of nodes per-cluster and their size (e.g. CPU cores & RAM).
    • Aggregate counts of logical resources like Clusters, Projects, Namespaces, and Pods.
    • Counts of what driver was used to deploy clusters and nodes (e.g. GKE vs EC2 vs Imported vs Custom).
    • Versions of Kubernetes components, Operating Systems and Docker that are deployed on nodes.
    • Whether some optional components are enabled or not (e.g. which auth providers are used).
    • The image name & version of Rancher that is running.
    • A unique randomly-generated identifier for this installation.

    Can I see the information that is being sent?​

    If Telemetry is enabled, you can go to https://<your rancher server>/v1-telemetry in your installation to see the current data.

    If Telemetry is not enabled, the process that collects the data is not running, so there is nothing being collected to look at.

    How do I turn it on or off?​

    After initial setup, an administrator can go to the Settings page in the Global section of the UI and click Edit to change the telemetry-opt setting to either in or out.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started.html b/v2.5/getting-started.html index c55414e6b17..94e12c67087 100644 --- a/v2.5/getting-started.html +++ b/v2.5/getting-started.html @@ -5,13 +5,13 @@ Getting Started | Rancher Manager - +
    Version: v2.5

    Getting Started

    To get up and running with Rancher quickly, we have included a Getting Started section.

    The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

    Please see the introduction, quick start guides, and the installation and upgrade sections for more.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html index 77827c79b62..a13dd97d849 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/configure-layer-7-nginx-load-balancer.html @@ -5,7 +5,7 @@ Docker Install with TLS Termination at Layer-7 NGINX Load Balancer | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Docker Install with TLS Termination at Layer-7 NGINX Load Balancer

    For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it conjunction.

    A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.

    This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer-7 NGINX load balancer.

    Want to skip the external load balancer? See Docker Installation instead.

    Requirements for OS, Docker, Hardware, and Networking​

    Make sure that your node fulfills the general installation requirements.

    1. Provision Linux Host​

    Provision a single Linux host according to our Requirements to launch your Rancher Server.

    2. Choose an SSL Option and Install Rancher​

    For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

    Do you want to...

    • Complete an Air Gap Installation?
    • Record all transactions with the Rancher API?

    See Advanced Options below before continuing.

    Choose from the following options:

    Option A-Bring Your Own Certificate: Self-Signed

    If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you'll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate.

    Prerequisites: Create a self-signed certificate.

    • The certificate files must be in PEM format.

    To Install Rancher Using a Self-Signed Cert:

    1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.

      docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
        rancher/rancher:latest
    Option B-Bring Your Own Certificate: Signed by Recognized CA

    If your cluster is public facing, it's best to use a certificate signed by a recognized CA.

    Prerequisites:

    • The certificate files must be in PEM format.

    To Install Rancher Using a Cert Signed by a Recognized CA:

    If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the --no-cacerts parameter to the container.

    1. Enter the following command.

      ```
      docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      rancher/rancher:latest --no-cacerts
      ```

    3. Configure Load Balancer​

    When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header X-Forwarded-Proto: https header, this redirect is disabled.

    The load balancer or proxy has to be configured to support the following:

    • WebSocket connections

    • SPDY / HTTP/2 protocols

    • Passing / setting the following headers:

      HeaderValueDescription
      HostHostname used to reach Rancher.To identify the server requested by the client.
      X-Forwarded-ProtohttpsTo identify the protocol that a client used to connect to the load balancer or proxy.

      Note: If this header is present, rancher/rancher does not redirect HTTP to HTTPS.
      X-Forwarded-PortPort used to reach Rancher.To identify the protocol that client used to connect to the load balancer or proxy.
      X-Forwarded-ForIP of the client connection.To identify the originating IP address of a client.

    Example NGINX configuration​

    This NGINX configuration is tested on NGINX 1.14.

    Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

    • Replace rancher-server with the IP address or hostname of the node running the Rancher container.
    • Replace both occurrences of FQDN to the DNS name for Rancher.
    • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
    worker_processes 4;
    worker_rlimit_nofile 40000;

    events {
        worker_connections 8192;
    }

    http {
        upstream rancher {
            server rancher-server:80;
        }

        map $http_upgrade $connection_upgrade {
            default Upgrade;
            ''      close;
        }

        server {
            listen 443 ssl http2;
            server_name FQDN;
            ssl_certificate /certs/fullchain.pem;
            ssl_certificate_key /certs/privkey.pem;

            location / {
                proxy_set_header Host $host;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_pass http://rancher;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                proxy_read_timeout 900s;
                proxy_buffering off;
            }
        }

        server {
            listen 80;
            server_name FQDN;
            return 301 https://$server_name$request_uri;
        }
    }

    What's Next?​

    • Recommended: Review Single Node Backup and Restore. Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
    • Create a Kubernetes cluster: Provisioning Kubernetes Clusters.

    FAQ and Troubleshooting​

    For help troubleshooting certificates, see this section.

    Advanced Options​

    API Auditing​

    If you want to record all transactions with the Rancher API, enable the API Auditing feature by adding the flags below into your install command.

    -e AUDIT_LEVEL=1 \
    -e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
    -e AUDIT_LOG_MAXAGE=20 \
    -e AUDIT_LOG_MAXBACKUP=20 \
    -e AUDIT_LOG_MAXSIZE=100 \

    Air Gap​

    If you are visiting this page to complete an Air Gap Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

    Example:

     <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

    Persistent Data​

    Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

    You can bind mount a host volume to this location to preserve data on the host it is running on:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /opt/rancher:/var/lib/rancher \
      --privileged \
      rancher/rancher:latest

    As of Rancher v2.5, privileged access is required.

    This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).

    Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - TCP and UDP Load Balancer.

    upstream rancher {
        server rancher-server:80;
    }

    map $http_upgrade $connection_upgrade {
        default Upgrade;
        ''      close;
    }

    server {
        listen 443 ssl http2;
        server_name rancher.yourdomain.com;
        ssl_certificate /etc/your_certificate_directory/fullchain.pem;
        ssl_certificate_key /etc/your_certificate_directory/privkey.pem;

        location / {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Port $server_port;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_pass http://rancher;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
            proxy_read_timeout 900s;
            proxy_buffering off;
        }
    }

    server {
        listen 80;
        server_name rancher.yourdomain.com;
        return 301 https://$server_name$request_uri;
    }

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html index 41902301f62..bce1fbb51da 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/enable-api-audit-log.html @@ -5,13 +5,13 @@ Enabling the API Audit Log to Record System Events | Rancher Manager - +
    Version: v2.5

    Enabling the API Audit Log to Record System Events

    You can enable the API audit log to record the sequence of system events initiated by individual users. You can know what happened, when it happened, who initiated it, and what cluster it affected. When you enable this feature, all requests to the Rancher API and all responses from it are written to a log.

    You can enable API Auditing during Rancher installation or upgrade.

    Enabling API Audit Log​

    The Audit Log is enabled and configured by passing environment variables to the Rancher server container. See the following to enable on your installation.

    API Audit Log Options​

    The usage below defines rules about what the audit log should record and what data it should include:

    ParameterDescription
    AUDIT_LEVEL0 - Disable audit log (default setting).
    1 - Log event metadata.
    2 - Log event metadata and request body.
    3 - Log event metadata, request body, and response body. Each log transaction for a request/response pair uses the same auditID value.

    See Audit Level Logging for a table that displays what each setting logs.
    AUDIT_LOG_PATHLog path for Rancher Server API. Default path is /var/log/auditlog/rancher-api-audit.log. You can mount the log directory to host.

    Usage Example: AUDIT_LOG_PATH=/my/custom/path/
    AUDIT_LOG_MAXAGEDefined the maximum number of days to retain old audit log files. Default is 10 days.
    AUDIT_LOG_MAXBACKUPDefines the maximum number of audit log files to retain. Default is 10.
    AUDIT_LOG_MAXSIZEDefines the maximum size in megabytes of the audit log file before it gets rotated. Default size is 100M.

    Audit Log Levels​

    The following table displays what parts of API transactions are logged for each AUDIT_LEVEL setting.

    AUDIT_LEVEL SettingRequest MetadataRequest BodyResponse MetadataResponse Body
    0
    1✓
    2✓✓
    3✓✓✓✓

    Viewing API Audit Logs​

    Docker Install​

    Share the AUDIT_LOG_PATH directory (Default: /var/log/auditlog) with the host system. The log can be parsed by standard CLI tools or forwarded on to a log collection tool like Fluentd, Filebeat, Logstash, etc.

    Kubernetes Install​

    Enabling the API Audit Log with the Helm chart install will create a rancher-audit-log sidecar container in the Rancher pod. This container will stream the log to standard output (stdout). You can view the log as you would any container log.

    The rancher-audit-log container is part of the rancher pod in the cattle-system namespace.

    CLI​

    kubectl -n cattle-system logs -f rancher-84d886bdbb-s4s69 rancher-audit-log

    Rancher Web GUI​

    1. From the context menu, select Cluster: local > System.
    2. From the main navigation bar, choose Resources > Workloads. Find the cattle-system namespace. Open the rancher workload by clicking its link.
    3. Pick one of the rancher pods and select ⋮ > View Logs.
    4. From the Logs drop-down, select rancher-audit-log.

    Shipping the Audit Log​

    You can enable Rancher's built in log collection and shipping for the cluster to ship the audit and other services logs to a supported collection endpoint. See Logging for details.

    Audit Log Samples​

    After you enable auditing, each API request or response is logged by Rancher in the form of JSON. Each of the following code samples provide examples of how to identify each API transaction.

    Metadata Level​

    If you set your AUDIT_LEVEL to 1, Rancher logs the metadata header for every API request, but not the body. The header provides basic information about the API transaction, such as the transaction's ID, who initiated the transaction, the time it occurred, etc.

    {
      "auditID": "30022177-9e2e-43d1-b0d0-06ef9d3db183",
      "requestURI": "/v3/schemas",
      "sourceIPs": ["::1"],
      "user": {
        "name": "user-f4tt2",
        "group": ["system:authenticated"]
      },
      "verb": "GET",
      "stage": "RequestReceived",
      "stageTimestamp": "2018-07-20 10:22:43 +0800"
    }

    Metadata and Request Body Level​

    If you set your AUDIT_LEVEL to 2, Rancher logs the metadata header and body for every API request.

    The code sample below depicts an API request, with both its metadata header and body.

    {
      "auditID": "ef1d249e-bfac-4fd0-a61f-cbdcad53b9bb",
      "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
      "sourceIPs": ["::1"],
      "user": {
        "name": "user-f4tt2",
        "group": ["system:authenticated"]
      },
      "verb": "PUT",
      "stage": "RequestReceived",
      "stageTimestamp": "2018-07-20 10:28:08 +0800",
      "requestBody": {
        "hostIPC": false,
        "hostNetwork": false,
        "hostPID": false,
        "paused": false,
        "annotations": {},
        "baseType": "workload",
        "containers": [
          {
            "allowPrivilegeEscalation": false,
            "image": "nginx",
            "imagePullPolicy": "Always",
            "initContainer": false,
            "name": "nginx",
            "ports": [
              {
                "containerPort": 80,
                "dnsName": "nginx-nodeport",
                "kind": "NodePort",
                "name": "80tcp01",
                "protocol": "TCP",
                "sourcePort": 0,
                "type": "/v3/project/schemas/containerPort"
              }
            ],
            "privileged": false,
            "readOnly": false,
            "resources": {
              "type": "/v3/project/schemas/resourceRequirements",
              "requests": {},
              "limits": {}
            },
            "restartCount": 0,
            "runAsNonRoot": false,
            "stdin": true,
            "stdinOnce": false,
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "tty": true,
            "type": "/v3/project/schemas/container",
            "environmentFrom": [],
            "capAdd": [],
            "capDrop": [],
            "livenessProbe": null,
            "volumeMounts": []
          }
        ],
        "created": "2018-07-18T07:34:16Z",
        "createdTS": 1531899256000,
        "creatorId": null,
        "deploymentConfig": {
          "maxSurge": 1,
          "maxUnavailable": 0,
          "minReadySeconds": 0,
          "progressDeadlineSeconds": 600,
          "revisionHistoryLimit": 10,
          "strategy": "RollingUpdate"
        },
        "deploymentStatus": {
          "availableReplicas": 1,
          "conditions": [
            {
              "lastTransitionTime": "2018-07-18T07:34:38Z",
              "lastTransitionTimeTS": 1531899278000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "Deployment has minimum availability.",
              "reason": "MinimumReplicasAvailable",
              "status": "True",
              "type": "Available"
            },
            {
              "lastTransitionTime": "2018-07-18T07:34:16Z",
              "lastTransitionTimeTS": 1531899256000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
              "reason": "NewReplicaSetAvailable",
              "status": "True",
              "type": "Progressing"
            }
          ],
          "observedGeneration": 2,
          "readyReplicas": 1,
          "replicas": 1,
          "type": "/v3/project/schemas/deploymentStatus",
          "unavailableReplicas": 0,
          "updatedReplicas": 1
        },
        "dnsPolicy": "ClusterFirst",
        "id": "deployment:default:nginx",
        "labels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        },
        "name": "nginx",
        "namespaceId": "default",
        "projectId": "c-bcz5t:p-fdr4s",
        "publicEndpoints": [
          {
            "addresses": ["10.64.3.58"],
            "allNodes": true,
            "ingressId": null,
            "nodeId": null,
            "podId": null,
            "port": 30917,
            "protocol": "TCP",
            "serviceId": "default:nginx-nodeport",
            "type": "publicEndpoint"
          }
        ],
        "restartPolicy": "Always",
        "scale": 1,
        "schedulerName": "default-scheduler",
        "selector": {
          "matchLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "type": "/v3/project/schemas/labelSelector"
        },
        "state": "active",
        "terminationGracePeriodSeconds": 30,
        "transitioning": "no",
        "transitioningMessage": "",
        "type": "deployment",
        "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
        "workloadAnnotations": {
          "deployment.kubernetes.io/revision": "1",
          "field.cattle.io/creatorId": "user-f4tt2"
        },
        "workloadLabels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        },
        "scheduling": {
          "node": {}
        },
        "description": "my description",
        "volumes": []
      }
    }

    Metadata, Request Body, and Response Body Level​

    If you set your AUDIT_LEVEL to 3, Rancher logs:

    • The metadata header and body for every API request.
    • The metadata header and body for every API response.

    Request​

    The code sample below depicts an API request, with both its metadata header and body.

    {
      "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
      "requestURI": "/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
      "sourceIPs": ["::1"],
      "user": {
        "name": "user-f4tt2",
        "group": ["system:authenticated"]
      },
      "verb": "PUT",
      "stage": "RequestReceived",
      "stageTimestamp": "2018-07-20 10:33:06 +0800",
      "requestBody": {
        "hostIPC": false,
        "hostNetwork": false,
        "hostPID": false,
        "paused": false,
        "annotations": {},
        "baseType": "workload",
        "containers": [
          {
            "allowPrivilegeEscalation": false,
            "image": "nginx",
            "imagePullPolicy": "Always",
            "initContainer": false,
            "name": "nginx",
            "ports": [
              {
                "containerPort": 80,
                "dnsName": "nginx-nodeport",
                "kind": "NodePort",
                "name": "80tcp01",
                "protocol": "TCP",
                "sourcePort": 0,
                "type": "/v3/project/schemas/containerPort"
              }
            ],
            "privileged": false,
            "readOnly": false,
            "resources": {
              "type": "/v3/project/schemas/resourceRequirements",
              "requests": {},
              "limits": {}
            },
            "restartCount": 0,
            "runAsNonRoot": false,
            "stdin": true,
            "stdinOnce": false,
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "tty": true,
            "type": "/v3/project/schemas/container",
            "environmentFrom": [],
            "capAdd": [],
            "capDrop": [],
            "livenessProbe": null,
            "volumeMounts": []
          }
        ],
        "created": "2018-07-18T07:34:16Z",
        "createdTS": 1531899256000,
        "creatorId": null,
        "deploymentConfig": {
          "maxSurge": 1,
          "maxUnavailable": 0,
          "minReadySeconds": 0,
          "progressDeadlineSeconds": 600,
          "revisionHistoryLimit": 10,
          "strategy": "RollingUpdate"
        },
        "deploymentStatus": {
          "availableReplicas": 1,
          "conditions": [
            {
              "lastTransitionTime": "2018-07-18T07:34:38Z",
              "lastTransitionTimeTS": 1531899278000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "Deployment has minimum availability.",
              "reason": "MinimumReplicasAvailable",
              "status": "True",
              "type": "Available"
            },
            {
              "lastTransitionTime": "2018-07-18T07:34:16Z",
              "lastTransitionTimeTS": 1531899256000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
              "reason": "NewReplicaSetAvailable",
              "status": "True",
              "type": "Progressing"
            }
          ],
          "observedGeneration": 2,
          "readyReplicas": 1,
          "replicas": 1,
          "type": "/v3/project/schemas/deploymentStatus",
          "unavailableReplicas": 0,
          "updatedReplicas": 1
        },
        "dnsPolicy": "ClusterFirst",
        "id": "deployment:default:nginx",
        "labels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        },
        "name": "nginx",
        "namespaceId": "default",
        "projectId": "c-bcz5t:p-fdr4s",
        "publicEndpoints": [
          {
            "addresses": ["10.64.3.58"],
            "allNodes": true,
            "ingressId": null,
            "nodeId": null,
            "podId": null,
            "port": 30917,
            "protocol": "TCP",
            "serviceId": "default:nginx-nodeport",
            "type": "publicEndpoint"
          }
        ],
        "restartPolicy": "Always",
        "scale": 1,
        "schedulerName": "default-scheduler",
        "selector": {
          "matchLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "type": "/v3/project/schemas/labelSelector"
        },
        "state": "active",
        "terminationGracePeriodSeconds": 30,
        "transitioning": "no",
        "transitioningMessage": "",
        "type": "deployment",
        "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
        "workloadAnnotations": {
          "deployment.kubernetes.io/revision": "1",
          "field.cattle.io/creatorId": "user-f4tt2"
        },
        "workloadLabels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        },
        "scheduling": {
          "node": {}
        },
        "description": "my decript",
        "volumes": []
      }
    }

    Response​

    The code sample below depicts an API response, with both its metadata header and body.

    {
      "auditID": "a886fd9f-5d6b-4ae3-9a10-5bff8f3d68af",
      "responseStatus": "200",
      "stage": "ResponseComplete",
      "stageTimestamp": "2018-07-20 10:33:06 +0800",
      "responseBody": {
        "actionLinks": {
          "pause": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=pause",
          "resume": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=resume",
          "rollback": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx?action=rollback"
        },
        "annotations": {},
        "baseType": "workload",
        "containers": [
          {
            "allowPrivilegeEscalation": false,
            "image": "nginx",
            "imagePullPolicy": "Always",
            "initContainer": false,
            "name": "nginx",
            "ports": [
              {
                "containerPort": 80,
                "dnsName": "nginx-nodeport",
                "kind": "NodePort",
                "name": "80tcp01",
                "protocol": "TCP",
                "sourcePort": 0,
                "type": "/v3/project/schemas/containerPort"
              }
            ],
            "privileged": false,
            "readOnly": false,
            "resources": {
              "type": "/v3/project/schemas/resourceRequirements"
            },
            "restartCount": 0,
            "runAsNonRoot": false,
            "stdin": true,
            "stdinOnce": false,
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "tty": true,
            "type": "/v3/project/schemas/container"
          }
        ],
        "created": "2018-07-18T07:34:16Z",
        "createdTS": 1531899256000,
        "creatorId": null,
        "deploymentConfig": {
          "maxSurge": 1,
          "maxUnavailable": 0,
          "minReadySeconds": 0,
          "progressDeadlineSeconds": 600,
          "revisionHistoryLimit": 10,
          "strategy": "RollingUpdate"
        },
        "deploymentStatus": {
          "availableReplicas": 1,
          "conditions": [
            {
              "lastTransitionTime": "2018-07-18T07:34:38Z",
              "lastTransitionTimeTS": 1531899278000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "Deployment has minimum availability.",
              "reason": "MinimumReplicasAvailable",
              "status": "True",
              "type": "Available"
            },
            {
              "lastTransitionTime": "2018-07-18T07:34:16Z",
              "lastTransitionTimeTS": 1531899256000,
              "lastUpdateTime": "2018-07-18T07:34:38Z",
              "lastUpdateTimeTS": 1531899278000,
              "message": "ReplicaSet \"nginx-64d85666f9\" has successfully progressed.",
              "reason": "NewReplicaSetAvailable",
              "status": "True",
              "type": "Progressing"
            }
          ],
          "observedGeneration": 2,
          "readyReplicas": 1,
          "replicas": 1,
          "type": "/v3/project/schemas/deploymentStatus",
          "unavailableReplicas": 0,
          "updatedReplicas": 1
        },
        "dnsPolicy": "ClusterFirst",
        "hostIPC": false,
        "hostNetwork": false,
        "hostPID": false,
        "id": "deployment:default:nginx",
        "labels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        },
        "links": {
          "remove": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
          "revisions": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/revisions",
          "self": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
          "update": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx",
          "yaml": "https://localhost:8443/v3/project/c-bcz5t:p-fdr4s/workloads/deployment:default:nginx/yaml"
        },
        "name": "nginx",
        "namespaceId": "default",
        "paused": false,
        "projectId": "c-bcz5t:p-fdr4s",
        "publicEndpoints": [
          {
            "addresses": ["10.64.3.58"],
            "allNodes": true,
            "ingressId": null,
            "nodeId": null,
            "podId": null,
            "port": 30917,
            "protocol": "TCP",
            "serviceId": "default:nginx-nodeport"
          }
        ],
        "restartPolicy": "Always",
        "scale": 1,
        "schedulerName": "default-scheduler",
        "selector": {
          "matchLabels": {
            "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
          },
          "type": "/v3/project/schemas/labelSelector"
        },
        "state": "active",
        "terminationGracePeriodSeconds": 30,
        "transitioning": "no",
        "transitioningMessage": "",
        "type": "deployment",
        "uuid": "f998037d-8a5c-11e8-a4cf-0245a7ebb0fd",
        "workloadAnnotations": {
          "deployment.kubernetes.io/revision": "1",
          "field.cattle.io/creatorId": "user-f4tt2"
        },
        "workloadLabels": {
          "workload.user.cattle.io/workloadselector": "deployment-default-nginx"
        }
      }
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html index b03f5650b84..0a1e14d25a5 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/open-ports-with-firewalld.html @@ -5,13 +5,13 @@ Opening Ports with firewalld | Rancher Manager - +
    Version: v2.5

    Opening Ports with firewalld

    We recommend disabling firewalld. For Kubernetes 1.19.x and higher, firewalld must be turned off.

    Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm.

    For example, one Oracle Linux image in AWS has REJECT rules that stop Helm from communicating with Tiller:

    Chain INPUT (policy ACCEPT)
    target     prot opt source               destination
    ACCEPT     all  --  anywhere             anywhere             state RELATED,ESTABLISHED
    ACCEPT     icmp --  anywhere             anywhere
    ACCEPT     all  --  anywhere             anywhere
    ACCEPT     tcp  --  anywhere             anywhere             state NEW tcp dpt:ssh
    REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

    Chain FORWARD (policy ACCEPT)
    target     prot opt source               destination
    REJECT     all  --  anywhere             anywhere             reject-with icmp-host-prohibited

    Chain OUTPUT (policy ACCEPT)
    target     prot opt source               destination

    You can check the default firewall rules with this command:

    sudo iptables --list

    This section describes how to use firewalld to apply the firewall port rules for nodes in a high-availability Rancher server cluster.

    Prerequisite

    Install v7.x or later ofvfirewalld:

    yum install firewalld
    systemctl start firewalld
    systemctl enable firewalld

    Applying Firewall Port Rules

    In the Rancher high-availability installation instructions, the Rancher server is set up on three nodes that have all three Kubernetes roles: etcd, controlplane, and worker. If your Rancher server nodes have all three roles, run the following commands on each node:

    firewall-cmd --permanent --add-port=22/tcp
    firewall-cmd --permanent --add-port=80/tcp
    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --permanent --add-port=2376/tcp
    firewall-cmd --permanent --add-port=2379/tcp
    firewall-cmd --permanent --add-port=2380/tcp
    firewall-cmd --permanent --add-port=6443/tcp
    firewall-cmd --permanent --add-port=8472/udp
    firewall-cmd --permanent --add-port=9099/tcp
    firewall-cmd --permanent --add-port=10250/tcp
    firewall-cmd --permanent --add-port=10254/tcp
    firewall-cmd --permanent --add-port=30000-32767/tcp
    firewall-cmd --permanent --add-port=30000-32767/udp

    If your Rancher server nodes have separate roles, use the following commands based on the role of the node:

    # For etcd nodes, run the following commands:
    firewall-cmd --permanent --add-port=2376/tcp
    firewall-cmd --permanent --add-port=2379/tcp
    firewall-cmd --permanent --add-port=2380/tcp
    firewall-cmd --permanent --add-port=8472/udp
    firewall-cmd --permanent --add-port=9099/tcp
    firewall-cmd --permanent --add-port=10250/tcp

    # For control plane nodes, run the following commands:
    firewall-cmd --permanent --add-port=80/tcp
    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --permanent --add-port=2376/tcp
    firewall-cmd --permanent --add-port=6443/tcp
    firewall-cmd --permanent --add-port=8472/udp
    firewall-cmd --permanent --add-port=9099/tcp
    firewall-cmd --permanent --add-port=10250/tcp
    firewall-cmd --permanent --add-port=10254/tcp
    firewall-cmd --permanent --add-port=30000-32767/tcp
    firewall-cmd --permanent --add-port=30000-32767/udp

    # For worker nodes, run the following commands:
    firewall-cmd --permanent --add-port=22/tcp
    firewall-cmd --permanent --add-port=80/tcp
    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --permanent --add-port=2376/tcp
    firewall-cmd --permanent --add-port=8472/udp
    firewall-cmd --permanent --add-port=9099/tcp
    firewall-cmd --permanent --add-port=10250/tcp
    firewall-cmd --permanent --add-port=10254/tcp
    firewall-cmd --permanent --add-port=30000-32767/tcp
    firewall-cmd --permanent --add-port=30000-32767/udp

    After the firewall-cmd commands have been run on a node, use the following command to enable the firewall rules:

    firewall-cmd --reload

    Result: The firewall is updated so that Helm can communicate with the Rancher server nodes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html index 92e250e05d1..267c9813af4 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/tune-etcd-for-large-installs.html @@ -5,13 +5,13 @@ Tuning etcd for Large Installations | Rancher Manager - +
    Version: v2.5

    Tuning etcd for Large Installations

    When running larger Rancher installations with 15 or more clusters it is recommended to increase the default keyspace for etcd from the default 2GB. The maximum setting is 8GB and the host should have enough RAM to keep the entire dataset in memory. When increasing this value you should also increase the size of the host. The keyspace size can also be adjusted in smaller installations if you anticipate a high rate of change of pods during the garbage collection interval.

    The etcd data set is automatically cleaned up on a five minute interval by Kubernetes. There are situations, e.g. deployment thrashing, where enough events could be written to etcd and deleted before garbage collection occurs and cleans things up causing the keyspace to fill up. If you see mvcc: database space exceeded errors, in the etcd logs or Kubernetes API server logs, you should consider increasing the keyspace size. This can be accomplished by setting the quota-backend-bytes setting on the etcd servers.

    Example: This snippet of the RKE cluster.yml file increases the keyspace size to 5GB​

    # RKE cluster.yml
    ---
    services:
      etcd:
        extra_args:
          quota-backend-bytes: 5368709120

    Scaling etcd disk performance​

    You can follow the recommendations from the etcd docs on how to tune the disk priority on the host.

    Additionally, to reduce IO contention on the disks for etcd, you can use a dedicated device for the data and wal directory. Based on etcd best practices, mirroring RAID configurations are unnecessary because etcd replicates data between the nodes in the cluster. You can use striping RAID configurations to increase available IOPS.

    To implement this solution in an RKE cluster, the /var/lib/etcd/data and /var/lib/etcd/wal directories will need to have disks mounted and formatted on the underlying host. In the extra_args directive of the etcd service, you must include the wal_dir directory. Without specifying the wal_dir, etcd process will try to manipulate the underlying wal mount with insufficient permissions.

    # RKE cluster.yml
    ---
    services:
      etcd:
        extra_args:
          data-dir: '/var/lib/rancher/etcd/data/'
          wal-dir: '/var/lib/rancher/etcd/wal/wal_dir'
        extra_binds:
          - '/var/lib/etcd/data:/var/lib/rancher/etcd/data'
          - '/var/lib/etcd/wal:/var/lib/rancher/etcd/wal'
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html index c8e91096905..4fd8e60e362 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/istio-traffic-management-features.html @@ -5,13 +5,13 @@ UI for Istio Virtual Services and Destination Rules | Rancher Manager - +
    Version: v2.5

    UI for Istio Virtual Services and Destination Rules

    This feature enables a UI that lets you create, read, update and delete virtual services and destination rules, which are traffic management features of Istio.

    Prerequisite: Turning on this feature does not enable Istio. A cluster administrator needs to enable Istio for the cluster in order to use the feature.

    To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

    Environment Variable KeyDefault ValueStatusAvailable as of
    istio-virtual-service-uifalseExperimentalv2.3.0
    istio-virtual-service-uitrueGAv2.3.2

    About this Feature

    A central advantage of Istio's traffic management features is that they allow dynamic request routing, which is useful for canary deployments, blue/green deployments, or A/B testing.

    When enabled, this feature turns on a page that lets you configure some traffic management features of Istio using the Rancher UI. Without this feature, you need to use kubectl to manage traffic with Istio.

    The feature enables two UI tabs: one tab for Virtual Services and another for Destination Rules.

    • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to direct percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed. For details, refer to the Istio documentation.
    • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred. For details, refer to the Istio documentation.

    To see these tabs,

    1. Go to the project view in Rancher and click Resources > Istio.
    2. You will see tabs for Traffic Graph, which has the Kiali network visualization integrated into the UI, and Traffic Metrics, which shows metrics for the success rate and request volume of traffic to your services, among other metrics. Next to these tabs, you should see the tabs for Virtual Services and Destination Rules.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html index be3f6bb57b7..2254869c56d 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/rancher-on-arm64.html @@ -5,7 +5,7 @@ Running on ARM64 (Experimental) | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Running on ARM64 (Experimental)

    Important:

    Running on an ARM64 platform is currently an experimental feature and is not yet officially supported in Rancher. Therefore, we do not recommend using ARM64 based nodes in a production environment.

    The following options are available when using an ARM64 platform:

    • Running Rancher on ARM64 based node(s)

      • Only for Docker Install. Please note that the following installation command replaces the examples found in the Docker Install link:

        # In the last line `rancher/rancher:vX.Y.Z`, be certain to replace "X.Y.Z" with a released version in which ARM64 builds exist. For  example, if your matching version is v2.5.8, you would fill in this line with `rancher/rancher:v2.5.8`.
        docker run -d --restart=unless-stopped \
          -p 80:80 -p 443:443 \
          --privileged \
          rancher/rancher:vX.Y.Z

        Note: To check if your specific released version is compatible with the ARM64 architecture, you may navigate to your version's release notes in the following two ways:

    • Create custom cluster and adding ARM64 based node(s)

      • Kubernetes cluster version must be 1.12 or higher
      • CNI Network Provider must be Flannel

    • Importing clusters that contain ARM64 based nodes

      • Kubernetes cluster version must be 1.12 or higher

    Please see Cluster Options how to configure the cluster options.

    The following features are not tested:

    • Monitoring, alerts, notifiers, pipelines and logging
    • Launching apps from the catalog
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html index f01b2f9ae20..6dcc9f32bb4 100644 --- a/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html +++ b/v2.5/getting-started/installation-and-upgrade/advanced-options/enable-experimental-features/unsupported-storage-drivers.html @@ -5,13 +5,13 @@ Allow Unsupported Storage Drivers | Rancher Manager - +
    Version: v2.5

    Allow Unsupported Storage Drivers

    This feature allows you to use types for storage providers and provisioners that are not enabled by default.

    To enable or disable this feature, refer to the instructions on the main page about enabling experimental features.

    Environment Variable KeyDefault ValueDescription
    unsupported-storage-driversfalseThis feature enables types for storage providers and provisioners that are not enabled by default.

    Types for Persistent Volume Plugins that are Enabled by Default​

    Below is a list of storage types for persistent volume plugins that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

    NamePlugin
    Amazon EBS Diskaws-ebs
    AzureFileazure-file
    AzureDiskazure-disk
    Google Persistent Diskgce-pd
    Longhornflex-volume-longhorn
    VMware vSphere Volumevsphere-volume
    Locallocal
    Network File Systemnfs
    hostPathhost-path

    Types for StorageClass that are Enabled by Default​

    Below is a list of storage types for a StorageClass that are enabled by default. When enabling this feature flag, any persistent volume plugins that are not on this list are considered experimental and unsupported:

    NamePlugin
    Amazon EBS Diskaws-ebs
    AzureFileazure-file
    AzureDiskazure-disk
    Google Persistent Diskgce-pd
    Longhornflex-volume-longhorn
    VMware vSphere Volumevsphere-volume
    Locallocal
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html index c045e3e5fdc..66ec100f457 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/air-gapped-upgrades.html @@ -5,13 +5,13 @@ Rendering the Helm Template in an Air Gapped Environment | Rancher Manager - +
    Version: v2.5

    Rendering the Helm Template in an Air Gapped Environment

    These instructions assume you have already followed the instructions for a Kubernetes upgrade on this page, including the prerequisites, up until step 3. Upgrade Rancher.

    Rancher Helm Template Options​

    Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

    Based on the choice you made during installation, complete one of the procedures below.

    PlaceholderDescription
    <VERSION>The version number of the output tarball.
    <RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
    <REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
    <CERTMANAGER_VERSION>Cert-manager version running on k8s cluster.

    Option A: Default Self-signed Certificate​

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set certmanager.version=<CERTMANAGER_VERSION> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    Option B: Certificates from Files using Kubernetes Secrets​

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set ingress.tls.source=secret \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set ingress.tls.source=secret \
        --set privateCA=true \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    Apply the Rendered Templates​

    Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.

    Use kubectl to apply the rendered manifests.

    kubectl -n cattle-system apply -R -f ./rancher

    Verify the Upgrade

    Log into Rancher to confirm that the upgrade succeeded.

    Having network issues following upgrade?

    See Restoring Cluster Networking.

    Known Upgrade Issues

    A list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html index 587822aaf13..67d2f665820 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-aks.html @@ -5,14 +5,14 @@ Installing Rancher on Azure Kubernetes Service | Rancher Manager - +
    Version: v2.5

    Installing Rancher on Azure Kubernetes Service

    This page covers how to install Rancher on Microsoft's Azure Kubernetes Service (AKS).

    The guide uses command line tools to provision an AKS cluster with an ingress. If you prefer to provision your cluster using the Azure portal, refer to the official documentation.

    If you already have an AKS Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

    Prerequisites

    Note Deploying to Microsoft Azure will incur charges.

    • Microsoft Azure Account: A Microsoft Azure Account is required to create resources for deploying Rancher and Kubernetes.
    • Microsoft Azure Subscription: Use this link to follow a tutorial to create a Microsoft Azure subscription if you don't have one yet.
    • Micsoroft Azure Tenant: Use this link and follow instructions to create a Microsoft Azure tenant.
    • Your subscription has sufficient quota for at least 2 vCPUs. For details on Rancher server resource requirements, refer to this section
    • When installing Rancher with Helm in Azure, use the L7 load balancer to avoid networking issues. For more information, refer to the documentation on Azure load balancer limitations.

    1. Prepare your Workstation

    Install the following command line tools on your workstation:

    2. Create a Resource Group

    After installing the CLI, you will need to log in with your Azure account.

    az login

    Create a resource group to hold all relevant resources for your cluster. Use a location that applies to your use case.

    az group create --name rancher-rg --location eastus

    3. Create the AKS Cluster

    To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to this article for available sizes and options. When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

    az aks create \
      --resource-group rancher-rg \
      --name rancher-server \
      --kubernetes-version 1.20.5 \
      --node-count 3 \
      --node-vm-size Standard_D2_v3

    The cluster will take some time to be deployed.

    4. Get Access Credentials

    After the cluster is deployed, get the access credentials.

    az aks get-credentials --resource-group rancher-rg --name rancher-server

    This command merges your cluster's credentials into the existing kubeconfig and allows kubectl to interact with the cluster.

    5. Install an Ingress

    The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription.

    The following command installs an nginx-ingress-controller with a Kubernetes load balancer service.

    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    helm upgrade --install \
      ingress-nginx ingress-nginx/ingress-nginx \
      --namespace ingress-nginx \
      --set controller.service.type=LoadBalancer \
      --version 3.12.0 \
      --create-namespace

    6. Get Load Balancer IP

    To get the address of the load balancer, run:

    kubectl get service ingress-nginx-controller --namespace=ingress-nginx

    The result should look similar to the following:

    NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)
     AGE
    ingress-nginx-controller   LoadBalancer   10.0.116.18    40.31.180.83   80:31229/TCP,443:31050/TCP
     67s

    Save the EXTERNAL-IP.

    7. Set up DNS

    External traffic to the Rancher server will need to be directed at the load balancer you created.

    Set up a DNS to point at the EXTERNAL-IP that you saved. This DNS will be used as the Rancher server URL.

    There are many valid ways to set up the DNS. For help, refer to the Azure DNS documentation

    8. Install the Rancher Helm Chart

    Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

    Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html index 7000e425d05..3b6ae236081 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.html @@ -5,13 +5,13 @@ Installing Rancher on Amazon EKS | Rancher Manager - +
    Version: v2.5

    Installing Rancher on Amazon EKS

    This page covers two ways to install Rancher on EKS.

    The first is a guide for deploying the Rancher server on an EKS cluster using CloudFormation. This guide was created in collaboration with Amazon Web Services to show how to deploy Rancher following best practices.

    The second is a guide for installing an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.

    If you already have an EKS Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

    Automated Quickstart using AWS Best Practices

    Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS cluster following AWS best practices. The deployment guide is here.

    The quick start guide provides three options for deploying Rancher on EKS:

    • Deploy Rancher into a new VPC and new Amazon EKS cluster. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, Amazon EKS cluster, and other infrastructure components. It then deploys Rancher into this new EKS cluster.
    • Deploy Rancher into an existing VPC and a new Amazon EKS cluster. This option provisions Rancher in your existing AWS infrastructure.
    • Deploy Rancher into an existing VPC and existing Amazon EKS cluster. This option provisions Rancher in your existing AWS infrastructure.

    Deploying this Quick Start for a new virtual private cloud (VPC) and new Amazon EKS cluster using default parameters builds the following Rancher environment in the AWS Cloud:

    • A highly available architecture that spans three Availability Zones.*
    • A VPC configured with public and private subnets, according to AWS best practices, to provide you with your own virtual network on AWS.*
    • In the public subnets:
      • Managed network address translation (NAT) gateways to allow outbound internet access for resources.*
      • Linux bastion hosts in an Auto Scaling group to allow inbound Secure Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets.*
    • In the private subnets:
      • Kubernetes nodes in an Auto Scaling group.*
      • A Network Load Balancer (not shown) for accessing the Rancher console.
    • Rancher deployment using AWS Systems Manager automation.
    • Amazon EKS service for the EKS cluster, which provides the Kubernetes control plane.*
    • An Amazon Route 53 DNS record for accessing the Rancher deployment.

    * The CloudFormation template that deploys the Quick Start into an existing Amazon EKS cluster skips the components marked by asterisks and prompts you for your existing VPC configuration.

    Creating an EKS Cluster for the Rancher Server

    In this section, you'll install an EKS cluster with an ingress by using command line tools. This guide may be useful if you want to use fewer resources while trying out Rancher on EKS.

    Prerequisites:

    • You should already have an AWS account.
    • It is recommended to use an IAM user instead of the root AWS account. You will need the IAM user's access key and secret key to configure the AWS command line interface.
    • The IAM user needs the minimum IAM policies described in the official eksctl documentation.

    1. Prepare your Workstation​

    Install the following command line tools on your workstation:

    2. Configure the AWS CLI​

    To configure the AWS CLI, run the following command:

    aws configure

    Then enter the following values:

    ValueDescription
    AWS Access Key IDThe access key credential for the IAM user with EKS permissions.
    AWS Secret Access KeyThe secret key credential for the IAM user with EKS permissions.
    Default region nameAn AWS region where the cluster nodes will be located.
    Default output formatEnter json.

    3. Create the EKS Cluster​

    To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

    eksctl create cluster \
      --name rancher-server \
      --version 1.20 \
      --region us-west-2 \
      --nodegroup-name ranchernodes \
      --nodes 3 \
      --nodes-min 1 \
      --nodes-max 4 \
      --managed

    The cluster will take some time to be deployed with CloudFormation.

    4. Test the Cluster​

    To test the cluster, run:

    eksctl get cluster

    The result should look like the following:

    eksctl get cluster
    2021-03-18 15:09:35 [ℹ]  eksctl version 0.40.0
    2021-03-18 15:09:35 [ℹ]  using region us-west-2
    NAME        REGION      EKSCTL CREATED
    rancher-server-cluster      us-west-2   True

    5. Install an Ingress​

    The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.

    The following command installs an nginx-ingress-controller with a LoadBalancer service. This will result in an ELB (Elastic Load Balancer) in front of NGINX:

    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    helm upgrade --install \
      ingress-nginx ingress-nginx/ingress-nginx \
      --namespace ingress-nginx \
      --set controller.service.type=LoadBalancer \
      --version 3.12.0 \
      --create-namespace

    6. Get Load Balancer IP​

    To get the address of the load balancer, run:

    kubectl get service ingress-nginx-controller --namespace=ingress-nginx

    The result should look similar to the following:

    NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP                                                              PORT(S)
     AGE
    ingress-nginx-controller   LoadBalancer   10.100.90.18   a904a952c73bf4f668a17c46ac7c56ab-962521486.us-west-2.elb.amazonaws.com   80:31229/TCP,443:31050/TCP
     27m

    Save the EXTERNAL-IP.

    7. Set up DNS​

    External traffic to the Rancher server will need to be directed at the load balancer you created.

    Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.

    There are many valid ways to set up the DNS. For help, refer to the AWS documentation on routing traffic to an ELB load balancer.

    8. Install the Rancher Helm Chart​

    Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

    Use that DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html index ab9fd693a55..1fb211f1e2b 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-gke.html @@ -5,13 +5,13 @@ Installing Rancher on a Google Kubernetes Engine Cluster | Rancher Manager - +
    Version: v2.5

    Installing Rancher on a Google Kubernetes Engine Cluster

    In this section, you'll learn how to install Rancher using Google Kubernetes Engine.

    If you already have a GKE Kubernetes cluster, skip to the step about installing an ingress. Then install the Rancher Helm chart following the instructions on this page.

    Prerequisites

    • You will need a Google account.
    • You will need a Google Cloud billing account. You can manage your Cloud Billing accounts using the Google Cloud Console. For more information about the Cloud Console, visit General guide to the console.
    • You will need a cloud quota for at least one in-use IP address and at least 2 CPUs. For more details about hardware requirements for the Rancher server, refer to this section.

    1. Enable the Kubernetes Engine API

    Take the following steps to enable the Kubernetes Engine API:

    1. Visit the Kubernetes Engine page in the Google Cloud Console.
    2. Create or select a project.
    3. Open the project and enable the Kubernetes Engine API for the project. Wait for the API and related services to be enabled. This can take several minutes.
    4. Make sure that billing is enabled for your Cloud project. For information on how to enable billing for your project, refer to the Google Cloud documentation.

    2. Open the Cloud Shell

    Cloud Shell is a shell environment for managing resources hosted on Google Cloud. Cloud Shell comes preinstalled with the gcloud command-line tool and kubectl command-line tool. The gcloud tool provides the primary command-line interface for Google Cloud, and kubectl provides the primary command-line interface for running commands against Kubernetes clusters.

    The following sections describe how to launch the cloud shell from the Google Cloud Console or from your local workstation.

    Cloud Shell​

    To launch the shell from the Google Cloud Console, go to the upper-right corner of the console and click the terminal button. When hovering over the button, it is labeled Activate Cloud Shell.

    Local Shell​

    To install gcloud and kubectl, perform the following steps:

    1. Install the Cloud SDK by following these steps. The Cloud SDK includes the gcloud command-line tool. The steps vary based on your OS.

    2. After installing Cloud SDK, install the kubectl command-line tool by running the following command:

      gcloud components install kubectl

      In a later step, kubectl will be configured to use the new GKE cluster.

    3. Install Helm 3 if it is not already installed.

    4. Enable Helm experimental support for OCI images with the HELM_EXPERIMENTAL_OCI variable. Add the following line to ~/.bashrc (or ~/.bash_profile in macOS, or wherever your shell stores environment variables):

      export HELM_EXPERIMENTAL_OCI=1

    5. Run the following command to load your updated .bashrc file:

      source ~/.bashrc

      If you are running macOS, use this command:

      source ~/.bash_profile

    3. Configure the gcloud CLI

    Set up default gcloud settings using one of the following methods:

    • Using gcloud init, if you want to be walked through setting defaults.
    • Using gcloud config, to individually set your project ID, zone, and region.

    1. Run gcloud init and follow the directions:

      gcloud init

      If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

      gcloud init --console-only

    2. Follow the instructions to authorize gcloud to use your Google Cloud account and select the new project that you created.

    4. Confirm that gcloud is configured correctly

    Run:

    gcloud config list

    The output should resemble the following:

    [compute]
    region = us-west1 # Your chosen region
    zone = us-west1-b # Your chosen zone
    [core]
    account = <Your email>
    disable_usage_reporting = True
    project = <Your project ID>

    Your active configuration is: [default]

    5. Create a GKE Cluster

    The following command creates a three-node cluster.

    Replace cluster-name with the name of your new cluster.

    When choosing a Kubernetes version, be sure to first consult the support matrix to find the highest version of Kubernetes that has been validated for your Rancher version.

    gcloud container clusters create cluster-name --num-nodes=3 --cluster-version=1.20.10-gke.301

    6. Get Authentication Credentials

    After creating your cluster, you need to get authentication credentials to interact with the cluster:

    gcloud container clusters get-credentials cluster-name

    This command configures kubectl to use the cluster you created.

    7. Install an Ingress

    The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.

    The following command installs an nginx-ingress-controller with a LoadBalancer service:

    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    helm upgrade --install \
      ingress-nginx ingress-nginx/ingress-nginx \
      --namespace ingress-nginx \
      --set controller.service.type=LoadBalancer \
      --version 3.12.0 \
      --create-namespace

    8. Get the Load Balancer IP

    To get the address of the load balancer, run:

    kubectl get service ingress-nginx-controller --namespace=ingress-nginx

    The result should look similar to the following:

    NAME                       TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
    ingress-nginx-controller   LoadBalancer   10.3.244.156   35.233.206.34   80:31876/TCP,443:32497/TCP   81s

    Save the EXTERNAL-IP.

    9. Set up DNS

    External traffic to the Rancher server will need to be directed at the load balancer you created.

    Set up a DNS to point at the external IP that you saved. This DNS will be used as the Rancher server URL.

    There are many valid ways to set up the DNS. For help, refer to the Google Cloud documentation about managing DNS records.

    10. Install the Rancher Helm chart

    Next, install the Rancher Helm chart by following the instructions on this page. The Helm instructions are the same for installing Rancher on any Kubernetes distribution.

    Use the DNS name from the previous step as the Rancher server URL when you install Rancher. It can be passed in as a Helm option. For example, if the DNS name is rancher.my.org, you could run the Helm installation command with the option --set hostname=rancher.my.org.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html index bbc8e287e75..55b6af75467 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.html @@ -5,13 +5,13 @@ Rollbacks | Rancher Manager - +
    Version: v2.5

    Rollbacks

    Rolling Back to Rancher v2.5.0+

    To roll back to Rancher v2.5.0+, use the Rancher Backups application and restore Rancher from backup.

    Rancher has to be started with the lower/previous version after a rollback.

    A restore is performed by creating a Restore custom resource.

    Important

    • Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to migrate rancher.
    • While restoring Rancher on the same setup, the Rancher deployment is manually scaled down before the restore starts, then the operator will scale it back up once the restore completes. As a result, Rancher and its UI will be unavailable until the restore is complete. While the UI is unavailable, use the original cluster kubeconfig with the restore YAML file: kubectl create -f restore.yaml.

    Scale the Rancher Deployment to 0​

    1. From the Global view, hover over the local cluster.
    2. Under Projects in local, click on System.
    3. From the cattle-system namespace section, find the rancher deployment.
    4. Select ⋮ > Edit.
    5. Change Scalable deployment of _ pods to 0.
    6. Scroll to the bottom and click Save.

    Create the Restore Custom Resource​

    1. In the Cluster Explorer, go to the dropdown menu in the upper left corner and click Rancher Backups.

      • Note: If the Rancher Backups app is not visible in the dropdown, you will need to install it from the Charts page in Apps & Marketplace. Refer here for more information.

    2. Click Restore.

    3. Create the Restore with the form or with YAML. For help creating the Restore resource using the online form, refer to the configuration reference and to the examples.

    4. To use the YAML editor, you can click Create > Create from YAML. Enter the Restore YAML. The following is an example Restore custom resource:

      apiVersion: resources.cattle.io/v1
      kind: Restore
      metadata:
        name: restore-migration
      spec:
        backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
        encryptionConfigSecretName: encryptionconfig
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: rancher-backups
            folder: rancher
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com

      For help configuring the Restore, refer to the configuration reference and to the examples.

    5. Click Create.

    Result: The backup file is created and updated to the target storage location. The resources are restored in this order:

    1. Custom Resource Definitions (CRDs)
    2. Cluster-scoped resources
    3. Namespaced resources

    To check how the restore is progressing, you can check the logs of the operator. Follow these steps to get the logs:

    kubectl get pods -n cattle-resources-system
    kubectl logs -n cattle-resources-system -f

    Roll back to a previous Rancher version​

    Rancher can be rolled back using the Helm CLI. To roll back to the previous version:

    helm rollback rancher -n cattle-system

    If the previous revision is not the intended target, you can specify a revision to roll back to. To see the deployment history:

    helm history rancher -n cattle-system

    When the target revision is determined, perform the rollback. This example will roll back to revision 3:

    helm rollback rancher 3 -n cattle-system

    Rolling Back to Rancher v2.2-v2.4+

    To roll back to Rancher before v2.5, follow the procedure detailed here: Restoring Backups — Kubernetes installs Restoring a snapshot of the Rancher server cluster will revert Rancher to the version and state at the time of the snapshot.

    For information on how to roll back Rancher installed with Docker, refer to this page.

    Managed clusters are authoritative for their state. This means restoring the rancher server will not revert workload deployments or changes made on managed clusters after the snapshot was taken.

    Rolling Back to Rancher v2.0-v2.1

    Rolling back to Rancher v2.0-v2.1 is no longer supported. The instructions for rolling back to these versions are preserved here and are intended to be used only in cases where upgrading to Rancher v2.2+ is not feasible.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html index eb6d7ae417c..2de1b5c0ef9 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting the Rancher Server Kubernetes Cluster | Rancher Manager - +
    Version: v2.5

    Troubleshooting the Rancher Server Kubernetes Cluster

    This section describes how to troubleshoot an installation of Rancher on a Kubernetes cluster.

    Relevant Namespaces​

    Most of the troubleshooting will be done on objects in these 3 namespaces.

    • cattle-system - rancher deployment and pods.
    • ingress-nginx - Ingress controller pods and services.
    • cert-manager - cert-manager pods.

    "default backend - 404"​

    A number of things can cause the ingress-controller not to forward traffic to your rancher instance. Most of the time its due to a bad ssl configuration.

    Things to check

    Check if Rancher is Running​

    Use kubectl to check the cattle-system system namespace and see if the Rancher pods are in a Running state.

    kubectl -n cattle-system get pods

    NAME                           READY     STATUS    RESTARTS   AGE
    pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

    If the state is not Running, run a describe on the pod and check the Events.

    kubectl -n cattle-system describe pod

    ...
    Events:
      Type     Reason                 Age   From                Message
      ----     ------                 ----  ----                -------
      Normal   Scheduled              11m   default-scheduler   Successfully assigned rancher-784d94f59b-vgqzh to localhost
      Normal   SuccessfulMountVolume  11m   kubelet, localhost  MountVolume.SetUp succeeded for volume "rancher-token-dj4mt"
      Normal   Pulling                11m   kubelet, localhost  pulling image "rancher/rancher:v2.0.4"
      Normal   Pulled                 11m   kubelet, localhost  Successfully pulled image "rancher/rancher:v2.0.4"
      Normal   Created                11m   kubelet, localhost  Created container
      Normal   Started                11m   kubelet, localhost  Started container

    Check the Rancher Logs​

    Use kubectl to list the pods.

    kubectl -n cattle-system get pods

    NAME                           READY     STATUS    RESTARTS   AGE
    pod/rancher-784d94f59b-vgqzh   1/1       Running   0          10m

    Use kubectl and the pod name to list the logs from the pod.

    kubectl -n cattle-system logs -f rancher-784d94f59b-vgqzh

    Cert CN is "Kubernetes Ingress Controller Fake Certificate"​

    Use your browser to check the certificate details. If it says the Common Name is "Kubernetes Ingress Controller Fake Certificate", something may have gone wrong with reading or issuing your SSL cert.

    Note: if you are using LetsEncrypt to issue certs it can sometimes take a few minutes to issue the cert.

    Checking for issues with cert-manager issued certs (Rancher Generated or LetsEncrypt)​

    cert-manager has 3 parts.

    • cert-manager pod in the cert-manager namespace.
    • Issuer object in the cattle-system namespace.
    • Certificate object in the cattle-system namespace.

    Work backwards and do a kubectl describe on each object and check the events. You can track down what might be missing.

    For example there is a problem with the Issuer:

    kubectl -n cattle-system describe certificate
    ...
    Events:
      Type     Reason          Age                 From          Message
      ----     ------          ----                ----          -------
      Warning  IssuerNotReady  18s (x23 over 19m)  cert-manager  Issuer rancher not ready
    kubectl -n cattle-system describe issuer
    ...
    Events:
      Type     Reason         Age                 From          Message
      ----     ------         ----                ----          -------
      Warning  ErrInitIssuer  19m (x12 over 19m)  cert-manager  Error initializing issuer: secret "tls-rancher" not found
      Warning  ErrGetKeyPair  9m (x16 over 19m)   cert-manager  Error getting keypair for CA issuer: secret "tls-rancher" not found

    Checking for Issues with Your Own SSL Certs​

    Your certs get applied directly to the Ingress object in the cattle-system namespace.

    Check the status of the Ingress object and see if its ready.

    kubectl -n cattle-system describe ingress

    If its ready and the SSL is still not working you may have a malformed cert or secret.

    Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.

    kubectl -n ingress-nginx logs -f nginx-ingress-controller-rfjrq nginx-ingress-controller
    ...
    W0705 23:04:58.240571       7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found

    No matches for kind "Issuer"​

    The SSL configuration option you have chosen requires cert-manager to be installed before installing Rancher or else the following error is shown:

    Error: validation failed: unable to recognize "": no matches for kind "Issuer" in version "certmanager.k8s.io/v1alpha1"

    Install cert-manager and try installing Rancher again.

    Canal Pods show READY 2/3​

    The most common cause of this issue is port 8472/UDP is not open between the nodes. Check your local firewall, network routing or security groups.

    Once the network issue is resolved, the canal pods should timeout and restart to establish their connections.

    nginx-ingress-controller Pods show RESTARTS​

    The most common cause of this issue is the canal pods have failed to establish the overlay network. See canal Pods show READY 2/3 for troubleshooting.

    Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)​

    Some causes of this error include:

    • User specified to connect with does not have permission to access the Docker socket. This can be checked by logging into the host and running the command docker ps:
    $ ssh user@server
    user@server$ docker ps
    CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES

    See Manage Docker as a non-root user how to set this up properly.

    • When using RedHat/CentOS as operating system, you cannot use the user root to connect to the nodes because of Bugzilla #1527565. You will need to add a separate user and configure it to access the Docker socket. See Manage Docker as a non-root user how to set this up properly.

    • SSH server version is not version 6.7 or higher. This is needed for socket forwarding to work, which is used to connect to the Docker socket over SSH. This can be checked using sshd -V on the host you are connecting to, or using netcat:

    $ nc xxx.xxx.xxx.xxx 22
    SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.10

    Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: no key found​

    The key file specified as ssh_key_path cannot be accessed. Make sure that you specified the private key file (not the public key, .pub), and that the user that is running the rke command can access the private key file.

    Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain​

    The key file specified as ssh_key_path is not correct for accessing the node. Double-check if you specified the correct ssh_key_path for the node and if you specified the correct user to connect with.

    Failed to dial ssh using address [xxx.xxx.xxx.xxx:xx]: Error configuring SSH: ssh: cannot decode encrypted private keys​

    If you want to use encrypted private keys, you should use ssh-agent to load your keys with your passphrase. If the SSH_AUTH_SOCK environment variable is found in the environment where the rke command is run, it will be used automatically to connect to the node.

    Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?​

    The node is not reachable on the configured address and port.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html index acaa1da35a4..7e410d6f899 100644 --- a/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html +++ b/v2.5/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades.html @@ -5,13 +5,13 @@ Upgrades | Rancher Manager - +
    Version: v2.5

    Upgrades

    The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.

    For the instructions to upgrade Rancher installed on Kubernetes with RancherD, refer to this page.

    For the instructions to upgrade Rancher installed with Docker, refer to this page.

    To upgrade the components in your Kubernetes cluster, or the definition of the Kubernetes services or add-ons, refer to the upgrade documentation for RKE, the Rancher Kubernetes Engine.

    Prerequisites

    Access to kubeconfig​

    Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.

    If you installed Kubernetes with RKE, the config will have been created in the directory you ran rke up in.

    The kubeconfig can also be manually targeted for the intended cluster with the --kubeconfig tag (see: https://helm.sh/docs/helm/helm/)

    Review Known Issues​

    Review the list of known issues for each Rancher version, which can be found in the release notes on GitHub and on the Rancher forums.

    Note that upgrades to or from any chart in the rancher-alpha repository aren't supported.

    Helm Version​

    The upgrade instructions assume you are using Helm 3.

    For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. The Helm 2 upgrade page here provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

    For air gap installs: Populate private registry​

    For air gap installs only, collect and populate images for the new Rancher server version. Follow the guide to populate your private registry with the images for the Rancher version that you want to upgrade to.

    For upgrades from a Rancher server with a hidden local cluster​

    If you are upgrading to Rancher v2.5 from a Rancher server that was started with the Helm chart option --add-local=false, you will need to drop that flag when upgrading. Otherwise, the Rancher server will not start. The restricted-admin role can be used to continue restricting access to the local cluster. For more information, see this section.

    For upgrades with cert-manager older than 0.8.0​

    Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019. Upgrade cert-manager to the latest version by following these instructions.

    Upgrade Outline

    Follow the steps to upgrade Rancher server:

    1. Back up Your Kubernetes Cluster that is Running Rancher Server

    Use the backup application to back up Rancher.

    You'll use the backup as a restoration point if something goes wrong during upgrade.

    2. Update the Helm chart repository

    1. Update your local helm repo cache.

      helm repo update

    2. Get the repository name that you used to install Rancher.

      For information about the repos and their differences, see Helm Chart Repositories.

      • Latest: Recommended for trying out the newest features
        helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
      • Stable: Recommended for production environments
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      • Alpha: Experimental preview of upcoming releases.
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
        Note: Upgrades are not supported to, from, or between Alphas.
      helm repo list

      NAME                   URL
      stable                 https://charts.helm.sh/stable
      rancher-<CHART_REPO>     https://releases.rancher.com/server-charts/<CHART_REPO>

      Note: If you want to switch to a different Helm chart repository, please follow the steps on how to switch repositories. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.

    1. Fetch the latest chart to install Rancher from the Helm chart repository.

      This command will pull down the latest charts and save it in the current directory as a .tgz file.

      helm fetch rancher-<CHART_REPO>/rancher

      You can fetch the chart for the specific version you are upgrading to by adding in the --version= tag. For example:

      helm fetch rancher-<CHART_REPO>/rancher --version=2.5.16

    3. Upgrade Rancher

    This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.

    Air Gap Instructions: If you are installing Rancher in an air gapped environment, skip the rest of this page and render the Helm template by following the instructions on this page.

    Get the values, which were passed with --set, from the current Rancher Helm chart that is installed.

    helm get values rancher -n cattle-system

    hostname: rancher.my.org

    Note: There will be more values that are listed with this command. This is just an example of one of the values.

    If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow Option B: Reinstalling Rancher and cert-manager.

    Otherwise, follow Option A: Upgrading Rancher.

    Option A: Upgrading Rancher​

    Upgrade Rancher to the latest version with all your settings.

    Take all the values from the previous step and append them to the command using --set key=value:

    helm upgrade rancher rancher-<CHART_REPO>/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org

    Note: The above is an example, there may be more values from the previous step that need to be appended.

    Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:

    helm get values rancher -n cattle-system -o yaml > values.yaml

    helm upgrade rancher rancher-<CHART_REPO>/rancher \
      --namespace cattle-system \
      -f values.yaml \
      --version=2.5.16

    Option B: Reinstalling Rancher and cert-manager​

    If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.

    1. Uninstall Rancher

      helm delete rancher -n cattle-system

    2. Uninstall and reinstall cert-manager according to the instructions on the Upgrading Cert-Manager page.

    3. Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using --set key=value. Note: There will be many more options from the step 1 that need to be appended.

      helm install rancher rancher-<CHART_REPO>/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org

    4. Verify the Upgrade

    Log into Rancher to confirm that the upgrade succeeded.

    Having network issues following upgrade?

    See Restoring Cluster Networking.

    Known Upgrade Issues

    A list of known issues for each Rancher version can be found in the release notes on GitHub and on the Rancher forums.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/installation-requirements/install-docker.html b/v2.5/getting-started/installation-and-upgrade/installation-requirements/install-docker.html index 999078b86c5..ee4f87bdfd9 100644 --- a/v2.5/getting-started/installation-and-upgrade/installation-requirements/install-docker.html +++ b/v2.5/getting-started/installation-and-upgrade/installation-requirements/install-docker.html @@ -5,13 +5,13 @@ Installing Docker | Rancher Manager - +
    Version: v2.5

    Installing Docker

    Docker is required to be installed on nodes where the Rancher server will be installed with Helm or Docker.

    There are a couple of options for installing Docker. One option is to refer to the official Docker documentation about how to install Docker on Linux. The steps will vary based on the Linux distribution.

    Another option is to use one of Rancher's Docker installation scripts, which are available for most recent versions of Docker.

    For example, this command could be used to install Docker 20.10 on Ubuntu:

    curl https://releases.rancher.com/install-docker/20.10.sh | sh

    Rancher has installation scripts for every version of upstream Docker that Kubernetes supports. To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher's Docker installation scripts.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html b/v2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html index 4f76e7596d2..dce8c48f35d 100644 --- a/v2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html +++ b/v2.5/getting-started/installation-and-upgrade/installation-requirements/port-requirements.html @@ -5,7 +5,7 @@ Port Requirements | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Port Requirements

    To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes.

    Rancher Nodes

    The following table lists the ports that need to be open to and from nodes that are running the Rancher server.

    The port requirements differ based on the Rancher server architecture.

    As of Rancher v2.5, Rancher can be installed on any Kubernetes cluster. For Rancher installs on a K3s, RKE, or RKE2 Kubernetes cluster, refer to the tabs below. For other Kubernetes distributions, refer to the distribution's documentation for the port requirements for cluster nodes.

    Notes:

    • Rancher nodes may also require additional outbound access for any external authentication provider which is configured (LDAP for example).
    • Kubernetes recommends TCP 30000-32767 for node port services.
    • For firewalls, traffic may need to be enabled within the cluster and pod CIDR.

    Ports for Rancher Server Nodes on K3s​

    Click to expand

    The K3s server needs port 6443 to be accessible by the nodes.

    The nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used. The node should not listen on any other port. K3s uses reverse tunneling such that the nodes make outbound connections to the server and all kubelet traffic runs through that tunnel. However, if you do not use Flannel and provide your own custom CNI, then port 8472 is not needed by K3s.

    If you wish to utilize the metrics server, you will need to open port 10250 on each node.

    Important: The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.

    The following tables break down the port requirements for inbound and outbound traffic:

    Inbound Rules for Rancher Server Nodes
    ProtocolPortSourceDescription
    TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
    TCP443
    • server nodes
    • agent nodes
    • hosted/registered Kubernetes
    • any source that needs to be able to use the Rancher UI or API
    		Rancher agent, Rancher UI/API, kubectl
    TCP6443K3s server nodesKubernetes API
    UDP8472K3s server and agent nodesRequired only for Flannel VXLAN.
    TCP10250K3s server and agent nodeskubelet
    Outbound Rules for Rancher Nodes
    ProtocolPortDestinationDescription
    TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
    TCP443git.rancher.ioRancher catalog
    TCP2376Any node IP from a node created using Node driverDocker daemon TLS port used by Docker Machine
    TCP6443Hosted/Imported Kubernetes APIKubernetes API server

    Ports for Rancher Server Nodes on RKE​

    Click to expand

    Typically Rancher is installed on three RKE nodes that all have the etcd, control plane and worker roles.

    The following tables break down the port requirements for traffic between the Rancher nodes:

    Rules for traffic between Rancher nodes
    ProtocolPortDescription
    TCP443Rancher agents
    TCP2379etcd client requests
    TCP2380etcd peer communication
    TCP6443Kubernetes apiserver
    UDP8472Canal/Flannel VXLAN overlay networking
    TCP9099Canal/Flannel livenessProbe/readinessProbe
    TCP10250Metrics server communication with all nodes
    TCP10254Ingress controller livenessProbe/readinessProbe

    The following tables break down the port requirements for inbound and outbound traffic:

    Inbound Rules for Rancher Nodes
    ProtocolPortSourceDescription
    TCP22RKE CLISSH provisioning of node by RKE
    TCP80Load Balancer/Reverse ProxyHTTP traffic to Rancher UI/API
    TCP443
    • Load Balancer/Reverse Proxy
    • IPs of all cluster nodes and other API/UI clients
    		HTTPS traffic to Rancher UI/API
    TCP6443Kubernetes API clientsHTTPS traffic to Kubernetes API
    Outbound Rules for Rancher Nodes
    ProtocolPortDestinationDescription
    TCP44335.160.43.145,35.167.242.46,52.33.59.17Rancher catalog (git.rancher.io)
    TCP22Any node created using a node driverSSH provisioning of node by node driver
    TCP2376Any node created using a node driverDocker daemon TLS port used by node driver
    TCP6443Hosted/Imported Kubernetes APIKubernetes API server
    TCPProvider dependentPort of the Kubernetes API endpoint in hosted clusterKubernetes API

    Ports for Rancher Server Nodes on RancherD or RKE2​

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    Click to expand

    The RancherD (or RKE2) server needs port 6443 and 9345 to be accessible by other nodes in the cluster.

    All nodes need to be able to reach other nodes over UDP port 8472 when Flannel VXLAN is used.

    If you wish to utilize the metrics server, you will need to open port 10250 on each node.

    Important: The VXLAN port on nodes should not be exposed to the world as it opens up your cluster network to be accessed by anyone. Run your nodes behind a firewall/security group that disables access to port 8472.

    Inbound Rules for RancherD or RKE2 Server Nodes
    ProtocolPortSourceDescription
    TCP9345RancherD/RKE2 agent nodesKubernetes API
    TCP6443RancherD/RKE2 agent nodesKubernetes API
    UDP8472RancherD/RKE2 server and agent nodesRequired only for Flannel VXLAN
    TCP10250RancherD/RKE2 server and agent nodeskubelet
    TCP2379RancherD/RKE2 server nodesetcd client port
    TCP2380RancherD/RKE2 server nodesetcd peer port
    TCP30000-32767RancherD/RKE2 server and agent nodesNodePort port range
    HTTP8080Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
    HTTPS8443
    • hosted/registered Kubernetes
    • any source that needs to be able to use the Rancher UI or API
    		Rancher agent, Rancher UI/API, kubectl. Not needed if you have LB doing TLS termination.

    Typically all outbound traffic is allowed.

    Ports for Rancher Server in Docker​

    Click to expand

    The following tables break down the port requirements for Rancher nodes, for inbound and outbound traffic:

    Inbound Rules for Rancher Node
    ProtocolPortSourceDescription
    TCP80Load balancer/proxy that does external SSL terminationRancher UI/API when external SSL termination is used
    TCP443
    • hosted/registered Kubernetes
    • any source that needs to be able to use the Rancher UI or API
    		Rancher agent, Rancher UI/API, kubectl
    Outbound Rules for Rancher Node
    ProtocolPortSourceDescription
    TCP22Any node IP from a node created using Node DriverSSH provisioning of nodes using Node Driver
    TCP443git.rancher.ioRancher catalog
    TCP2376Any node IP from a node created using a node driverDocker daemon TLS port used by Docker Machine
    TCP6443Hosted/Imported Kubernetes APIKubernetes API server

    Downstream Kubernetes Cluster Nodes

    Downstream Kubernetes clusters run your apps and services. This section describes what ports need to be opened on the nodes in downstream clusters so that Rancher can communicate with them.

    The port requirements differ depending on how the downstream cluster was launched. Each of the tabs below list the ports that need to be opened for different cluster types.

    The following diagram depicts the ports that are opened for each cluster type.

    Port Requirements for the Rancher Management Plane

    Basic Port Requirements

    Tip:

    If security isn't a large concern and you're okay with opening a few additional ports, you can use the table in Commonly Used Ports as your port reference instead of the comprehensive tables below.

    Ports for Rancher Launched Kubernetes Clusters using Node Pools​

    Click to expand

    The following table depicts the port requirements for Rancher Launched Kubernetes with nodes created in an Infrastructure Provider.

    Note: The required ports are automatically opened by Rancher during creation of clusters in cloud providers like Amazon EC2 or DigitalOcean.

    From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
    Rancher Nodes (1)22 TCPgit.rancher.io
    2376 TCP
    etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
    2380 TCP
    6443 TCP
    8472 UDP
    9099 TCP (4)
    Control Plane Nodes443 TCP (3)2379 TCP443 TCP
    2380 TCP
    6443 TCP
    8472 UDP
    10250 TCP
    9099 TCP (4)
    10254 TCP (4)
    Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
    8472 UDP
    9099 TCP (4)
    10254 TCP (4)
    Kubernetes API Clients6443 TCP (5)
    Workload Clients or Load Balancer30000-32767 TCP / UDP
    (nodeport)
    80 TCP (Ingress)
    443 TCP (Ingress)
    Notes:

    1. Nodes running standalone server or Rancher HA deployment.
    2. Required to fetch Rancher chart library.
    3. Only without external load balancer in front of Rancher.
    4. Local traffic to the node itself (not across nodes).
    5. Only if Authorized Cluster Endpoints are activated.

    Ports for Rancher Launched Kubernetes Clusters using Custom Nodes​

    Click to expand

    The following table depicts the port requirements for Rancher Launched Kubernetes with Custom Nodes.

    From / ToRancher Nodesetcd Plane NodesControl Plane NodesWorker Plane NodesExternal Rancher Load BalancerInternet
    Rancher Nodes (1)git.rancher.io
    etcd Plane Nodes443 TCP (3)2379 TCP443 TCP
    2380 TCP
    6443 TCP
    8472 UDP
    4789 UDP (6)
    9099 TCP (4)
    Control Plane Nodes443 TCP (3)2379 TCP443 TCP
    2380 TCP
    6443 TCP
    8472 UDP
    4789 UDP (6)
    10250 TCP
    9099 TCP (4)
    10254 TCP (4)
    Worker Plane Nodes443 TCP (3)6443 TCP443 TCP
    8472 UDP
    4789 UDP (6)
    9099 TCP (4)
    10254 TCP (4)
    Kubernetes API Clients6443 TCP (5)
    Workload Clients or Load Balancer30000-32767 TCP / UDP
    (nodeport)
    80 TCP (Ingress)
    443 TCP (Ingress)
    Notes:

    1. Nodes running standalone server or Rancher HA deployment.
    2. Required to fetch Rancher chart library.
    3. Only without external load balancer in front of Rancher.
    4. Local traffic to the node itself (not across nodes).
    5. Only if Authorized Cluster Endpoints are activated.
    6. Only if using Overlay mode on Windows cluster.

    Ports for Hosted Kubernetes Clusters​

    Click to expand

    The following table depicts the port requirements for hosted clusters.

    From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
    Rancher Nodes (1)Kubernetes API
    Endpoint Port (2)    		git.rancher.io
    8443 TCP
    9443 TCP
    Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
    Kubernetes API ClientsCluster / Provider Specific (6)
    Workload ClientCluster / Provider Specific (7)
    Notes:

    1. Nodes running standalone server or Rancher HA deployment.
    2. Only for hosted clusters.
    3. Required to fetch Rancher chart library.
    4. Only without external load balancer.
    5. From worker nodes.
    6. For direct access to the Kubernetes API without Rancher.
    7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

    Ports for Registered Clusters​

    Note: Registered clusters were called imported clusters before Rancher v2.5.

    Click to expand

    The following table depicts the port requirements for registered clusters.

    From / ToRancher NodesHosted / Imported ClusterExternal Rancher Load BalancerInternet
    Rancher Nodes (1)Kubernetes API
    Endpoint Port (2)    		git.rancher.io
    8443 TCP
    9443 TCP
    Hosted / Imported Cluster443 TCP (4)(5)443 TCP (5)
    Kubernetes API ClientsCluster / Provider Specific (6)
    Workload ClientCluster / Provider Specific (7)
    Notes:

    1. Nodes running standalone server or Rancher HA deployment.
    2. Only for hosted clusters.
    3. Required to fetch Rancher chart library.
    4. Only without external load balancer.
    5. From worker nodes.
    6. For direct access to the Kubernetes API without Rancher.
    7. Usually Ingress backed by infrastructure load balancer and/or nodeport.

    Other Port Considerations

    Commonly Used Ports​

    These ports are typically opened on your Kubernetes nodes, regardless of what type of cluster it is.

    ProtocolPortDescription
    TCP22Node driver SSH provisioning
    TCP179Calico BGP Port
    TCP2376Node driver Docker daemon TLS port
    TCP2379etcd client requests
    TCP2380etcd peer communication
    UDP8472Canal/Flannel VXLAN overlay networking
    UDP4789Flannel VXLAN overlay networking on Windows cluster
    TCP8443Rancher webhook
    TCP9099Canal/Flannel livenessProbe/readinessProbe
    TCP9100Default port required by Monitoring to scrape metrics from Linux node-exporters
    TCP9443Rancher webhook
    TCP9796Default port required by Monitoring to scrape metrics from Windows node-exporters
    TCP6783Weave Port
    UDP6783-6784Weave UDP Ports
    TCP10250Metrics server communication with all nodes API
    TCP10254Ingress controller livenessProbe/readinessProbe
    TCP/UDP30000-32767NodePort port range

    Local Node Traffic​

    Ports marked as local traffic (i.e., 9099 TCP) in the above requirements are used for Kubernetes healthchecks (livenessProbe andreadinessProbe). These healthchecks are executed on the node itself. In most cloud environments, this local traffic is allowed by default.

    However, this traffic may be blocked when:

    • You have applied strict host firewall policies on the node.
    • You are using nodes that have multiple interfaces (multihomed).

    In these cases, you have to explicitly allow this traffic in your host firewall, or in case of public/private cloud hosted machines (i.e. AWS or OpenStack), in your security group configuration. Keep in mind that when using a security group as source or destination in your security group, explicitly opening ports only applies to the private interface of the nodes / instances.

    Rancher AWS EC2 Security Group​

    When using the AWS EC2 node driver to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called rancher-nodes. The following rules are automatically added to this security group.

    TypeProtocolPort RangeSource/DestinationRule Type
    SSHTCP220.0.0.0/0Inbound
    HTTPTCP800.0.0.0/0Inbound
    Custom TCP RuleTCP4430.0.0.0/0Inbound
    Custom TCP RuleTCP23760.0.0.0/0Inbound
    Custom TCP RuleTCP2379-2380sg-xxx (rancher-nodes)Inbound
    Custom UDP RuleUDP4789sg-xxx (rancher-nodes)Inbound
    Custom TCP RuleTCP64430.0.0.0/0Inbound
    Custom UDP RuleUDP8472sg-xxx (rancher-nodes)Inbound
    Custom TCP RuleTCP10250-10252sg-xxx (rancher-nodes)Inbound
    Custom TCP RuleTCP10256sg-xxx (rancher-nodes)Inbound
    Custom TCP RuleTCP30000-327670.0.0.0/0Inbound
    Custom UDP RuleUDP30000-327670.0.0.0/0Inbound
    All trafficAllAll0.0.0.0/0Outbound

    Opening SUSE Linux Ports​

    SUSE Linux may have a firewall that blocks all ports by default. To open the ports needed for adding the host to a custom cluster,

    1. SSH into the instance.
    2. Start YaST in text mode:
    sudo yast2
    1. Navigate to Security and Users > Firewall > Zones:public > Ports. To navigate within the interface, follow the instructions here.
    2. To open the required ports, enter them into the TCP Ports and UDP Ports fields. In this example, ports 9796 and 10250 are also opened for monitoring. The resulting fields should look similar to the following:
    TCP Ports
    22, 80, 443, 2376, 2379, 2380, 6443, 9099, 9796, 10250, 10254, 30000-32767
    UDP Ports
    8472, 30000-32767
    1. When all required ports are enter, select Accept.

    Result: The node has the open ports required to be added to a custom cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html index d113a2fc198..0f815ba1358 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/docker-install-commands.html @@ -5,14 +5,14 @@ Docker Install Commands | Rancher Manager - +
    Version: v2.5

    Docker Install Commands

    The Docker installation is for Rancher users who want to test out Rancher.

    Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a docker run command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    For Rancher v2.5+, the backup application can be used to migrate the Rancher server from a Docker install to a Kubernetes install using these steps.

    For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

    Environment Variable KeyEnvironment Variable ValueDescription
    CATTLE_SYSTEM_DEFAULT_REGISTRY<REGISTRY.YOURDOMAIN.COM:PORT>Configure Rancher server to always pull from your private registry when provisioning clusters.
    CATTLE_SYSTEM_CATALOGbundledConfigure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror.

    Do you want to...

    Choose from the following options:

    Option A: Default Self-Signed Certificate​

    Click to expand

    If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

    Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder.

    PlaceholderDescription
    <REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
        --privileged \
        <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

    Option B: Bring Your Own Certificate: Self-Signed​

    Click to expand

    In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.

    Prerequisites: From a computer with an internet connection, create a self-signed certificate using OpenSSL or another method of your choice.

    • The certificate files must be in PEM format.
    • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the -v flag and provide the path to your certificates to mount them in your container.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <CA_CERTS.pem>The path to the certificate authority's certificate.
    <REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
        -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
        -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
        -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
        --privileged \
        <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

    Option C: Bring Your Own Certificate: Signed by Recognized CA​

    Click to expand

    In development or testing environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.

    Prerequisite: The certificate files must be in PEM format.

    After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <REGISTRY.YOURDOMAIN.COM:PORT>Your private registry URL and port.
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to install.

    Note: Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
        -p 80:80 -p 443:443 \
        --no-cacerts \
        -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
        -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
        -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        -e CATTLE_SYSTEM_CATALOG=bundled \ # Use the packaged Rancher system charts
        --privileged
        <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

    Note: If you don't intend to send telemetry data, opt out telemetry during the initial login.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html index f74cd969249..3baf55bb07e 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/infrastructure-private-registry.html @@ -5,7 +5,7 @@ 1. Set up Infrastructure and Private Registry | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    1. Set up Infrastructure and Private Registry

    In this section, you will provision the underlying infrastructure for your Rancher management server in an air gapped environment. You will also set up the private Docker registry that must be available to your Rancher node(s).

    An air gapped environment is an environment where the Rancher server is installed offline or behind a firewall.

    The infrastructure depends on whether you are installing Rancher on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container. For more information on each installation option, refer to this page.

    As of Rancher v2.5, Rancher can be installed on any Kubernetes cluster. The RKE and K3s Kubernetes infrastructure tutorials below are still included for convenience.

    We recommend setting up the following infrastructure for a high-availability installation:

    • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • An external database to store the cluster data. PostgreSQL, MySQL, and etcd are supported.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.
    • A private Docker registry to distribute Docker images to your machines.

    1. Set up Linux Nodes​

    These hosts will be disconnected from the internet, but require being able to connect with your private registry.

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up External Datastore​

    The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

    For a high-availability K3s installation, you will need to set up one of the following external databases:

    • PostgreSQL (certified against versions 10.7 and 11.5)
    • MySQL (certified against version 5.7)
    • etcd (certified against version 3.3.15)

    When you install Kubernetes, you will pass in details for K3s to connect to the database.

    For an example of one way to set up the database, refer to this tutorial for setting up a MySQL database on Amazon's RDS service.

    For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

    3. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    5. Set up a Private Docker Registry​

    Rancher supports air gap installs using a private registry. You must have your own private registry or other means of distributing Docker images to your machines.

    In a later step, when you set up your K3s Kubernetes cluster, you will create a private registries configuration file with details from this registry.

    If you need help with creating a private registry, please refer to the official Docker documentation.

    Next: Collect and Publish Images to your Private Registry​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html index d00e7fc04b7..1d20df57197 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-kubernetes.html @@ -5,7 +5,7 @@ 3. Install Kubernetes (Skip for Docker Installs) | Rancher Manager - + @@ -15,7 +15,7 @@ Also obtain the K3s install script at 
    INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

    Install K3s on each agent:

    INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

    Note, take care to ensure you replace myserver with the IP or valid DNS of the server and replace mynodetoken with the node-token from the server. The node-token is on the server at /var/lib/rancher/k3s/server/node-token

    Note: K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.

    4. Save and Start Using the kubeconfig File​

    When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    Note on Upgrading​

    Upgrading an air-gap environment can be accomplished in the following manner:

    1. Download the new air-gap images (tar file) from the releases page for the version of K3s you will be upgrading to. Place the tar in the /var/lib/rancher/k3s/agent/images/ directory on each node. Delete the old tar file.
    2. Copy and replace the old K3s binary in /usr/local/bin on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
    3. Restart the K3s service (if not restarted automatically by installer).

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html index 09db50b5bca..c2df5abf0f9 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/install-rancher-ha.html @@ -5,14 +5,14 @@ 4. Install Rancher | Rancher Manager - +
    Version: v2.5

    4. Install Rancher

    This section is about how to deploy Rancher for your air gapped environment in a high-availability Kubernetes installation. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Privileged Access for Rancher v2.5+​

    When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the --privileged option.

    Docker Instructions

    If you want to continue the air gapped installation using Docker commands, skip the rest of this page and follow the instructions on this page.

    Kubernetes Instructions

    Rancher recommends installing Rancher on a Kubernetes cluster. A highly available Kubernetes install is comprised of three nodes running the Rancher server components on a Kubernetes cluster. The persistence layer (etcd) is also replicated on these three nodes, providing redundancy and data duplication in case one of the nodes fails.

    This section describes installing Rancher:

    1. Add the Helm Chart Repository

    From a system that has access to the internet, fetch the latest Helm chart and copy the resulting manifests to a system that has access to the Rancher server cluster.

    1. If you haven't already, install helm locally on a workstation that has internet access. Note: Refer to the Helm version requirements to choose a version of Helm to install Rancher.

    2. Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

      • Latest: Recommended for trying out the newest features
        helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
      • Stable: Recommended for production environments
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      • Alpha: Experimental preview of upcoming releases.
        ```
        helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
        ```
        Note: Upgrades are not supported to, from, or between Alphas.

    3. Fetch the latest Rancher chart. This will pull down the chart and save it in the current directory as a .tgz file.

      helm fetch rancher-<CHART_REPO>/rancher

      If you require a specific version of Rancher, you can fetch this with the Helm --version parameter like in the following example:

      helm fetch rancher-stable/rancher --version=v2.4.8

    2. Choose your SSL Configuration

    Rancher Server is designed to be secure by default and requires SSL/TLS configuration.

    When Rancher is installed on an air gapped Kubernetes cluster, there are two recommended options for the source of the certificate.

    Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

    ConfigurationChart optionDescriptionRequires cert-manager
    Rancher Generated Self-Signed Certificatesingress.tls.source=rancherUse certificates issued by Rancher's generated CA (self signed)
    This is the default and does not need to be added when rendering the Helm template.    		yes
    Certificates from Filesingress.tls.source=secretUse your own certificate files by creating Kubernetes Secret(s).
    This option must be passed when rendering the Rancher Helm template.    		no

    Helm Chart Options for Air Gap Installations

    When setting up the Rancher Helm template, there are several options in the Helm chart that are designed specifically for air gap installations.

    Chart OptionChart ValueDescription
    certmanager.version<version>Configure proper Rancher TLS issuer depending of running cert-manager version.
    systemDefaultRegistry<REGISTRY.YOURDOMAIN.COM:PORT>Configure Rancher server to always pull from your private registry when provisioning clusters.
    useBundledSystemCharttrueConfigure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror.

    3. Render the Rancher Helm Template

    Based on the choice your made in 2. Choose your SSL Configuration, complete one of the procedures below.

    Option A: Default Self-Signed Certificate

    By default, Rancher generates a CA and uses cert-manager to issue the certificate for access to the Rancher server interface.

    Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade cert-manager documentation.

    1. Add the cert-manager repo​

    From a system connected to the internet, add the cert-manager repo to Helm:

    helm repo add jetstack https://charts.jetstack.io
    helm repo update

    2. Fetch the cert-manager chart​

    Fetch the latest cert-manager chart available from the Helm chart repository.

    helm fetch jetstack/cert-manager --version v1.5.1

    3. Render the cert-manager template​

    Render the cert-manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

    helm template cert-manager ./cert-manager-v1.5.1.tgz --output-dir . \
        --namespace cert-manager \
        --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller \
        --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook \
        --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector \
        --set startupapicheck.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-ctl

    4. Download the cert-manager CRD​

    Download the required CRD file for cert-manager:

    curl -L -o cert-manager/cert-manager-crd.yaml https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml

    5. Render the Rancher template​

    Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

    PlaceholderDescription
    <VERSION>The version number of the output tarball.
    <RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
    <REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
    <CERTMANAGER_VERSION>Cert-manager version running on k8s cluster.
    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set certmanager.version=<CERTMANAGER_VERSION> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    Optional: To install a specific Rancher version, set the rancherImageTag value, example: --set rancherImageTag=v2.5.8

    Option B: Certificates From Files using Kubernetes Secrets

    1. Create secrets​

    Create Kubernetes secrets from your own certificates for Rancher to use. The common name for the cert will need to match the hostname option in the command below, or the ingress controller will fail to provision the site for Rancher.

    2. Render the Rancher template​

    Render the Rancher template, declaring your chosen options. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.

    PlaceholderDescription
    <VERSION>The version number of the output tarball.
    <RANCHER.YOURDOMAIN.COM>The DNS name you pointed at your load balancer.
    <REGISTRY.YOURDOMAIN.COM:PORT>The DNS name for your private registry.
       helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set ingress.tls.source=secret \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    If you are using a Private CA signed cert, add --set privateCA=true following --set ingress.tls.source=secret:

       helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
        --no-hooks \ # prevent files for Helm hooks from being generated
        --namespace cattle-system \
        --set hostname=<RANCHER.YOURDOMAIN.COM> \
        --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
        --set ingress.tls.source=secret \
        --set privateCA=true \
        --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
        --set useBundledSystemChart=true # Use the packaged Rancher system charts

    Optional: To install a specific Rancher version, set the rancherImageTag value, example: --set rancherImageTag=v2.3.6

    Then refer to Adding TLS Secrets to publish the certificate files so Rancher and the ingress controller can use them.

    4. Install Rancher

    Copy the rendered manifest directories to a system that has access to the Rancher server cluster to complete installation.

    Use kubectl to create namespaces and apply the rendered manifests.

    If you choose to use self-signed certificates in B. Choose your SSL Configuration, install cert-manager.

    For Self-Signed Certificate Installs, Install Cert-manager​

    Click to expand

    If you are using self-signed certificates, install cert-manager:

    1. Create the namespace for cert-manager.
    kubectl create namespace cert-manager
    1. Create the cert-manager CustomResourceDefinitions (CRDs).
    kubectl apply -f cert-manager/cert-manager-crd.yaml
    > **Note:**
    > If you are running Kubernetes v1.15 or below, you will need to add the `--validate=false` flag to your `kubectl apply` command above, or else you will receive a validation error relating to the `x-kubernetes-preserve-unknown-fields` field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.
    1. Launch cert-manager.
    kubectl apply -R -f ./cert-manager

    Install Rancher with kubectl​

    kubectl create namespace cattle-system
    kubectl -n cattle-system apply -R -f ./rancher

    The installation is complete.

    Note: If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

    Additional Resources

    These resources could be helpful when installing Rancher:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html index 86131d9c0a2..3512dc807dd 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.html @@ -5,13 +5,13 @@ 2. Collect and Publish Images to your Private Registry | Rancher Manager - +
    Version: v2.5

    2. Collect and Publish Images to your Private Registry

    This section describes how to set up your private registry so that when you install Rancher, Rancher will pull all the required images from this registry.

    By default, all images used to provision Kubernetes clusters or launch any tools in Rancher, e.g. monitoring and logging, are pulled from Docker Hub. In an air gapped installation of Rancher, you will need a private registry that is located somewhere accessible by your Rancher server. Then, you will load the registry with all the images.

    Populating the private registry with images is the same process for installing Rancher with Docker and for installing Rancher on a Kubernetes cluster.

    The steps in this section differ depending on whether or not you are planning to use Rancher to provision a downstream cluster with Windows nodes or not. By default, we provide the steps of how to populate your private registry assuming that Rancher will provision downstream Kubernetes clusters with only Linux nodes. But if you plan on provisioning any downstream Kubernetes clusters using Windows nodes, there are separate instructions to support the images needed.

    Prerequisites:

    You must have a private registry available to use.

    If the registry has certs, follow this K3s documentation about adding a private registry. The certs and registry configuration files need to be mounted into the Rancher container.

    For Rancher servers that will only provision Linux clusters, these are the steps to populate your private registry.

    1. Find the required assets for your Rancher version
    2. Collect the cert-manager image (unless you are bringing your own certificates or terminating TLS on a load balancer)
    3. Save the images to your workstation
    4. Populate the private registry

    Prerequisites​

    These steps expect you to use a Linux workstation that has internet access, access to your private registry, and at least 20 GB of disk space.

    If you will use ARM64 hosts, the registry must support manifests. As of April 2020, Amazon Elastic Container Registry does not support manifests.

    1. Find the required assets for your Rancher version​

    1. Go to our releases page, find the Rancher v2.x.x release that you want to install, and click Assets. Note: Don't use releases marked rc or Pre-release, as they are not stable for production environments.

    2. From the release's Assets section, download the following files, which are required to install Rancher in an air gap environment:

    Release FileDescription
    rancher-images.txtThis file contains a list of images needed to install Rancher, provision clusters and user Rancher tools.
    rancher-save-images.shThis script pulls all the images in the rancher-images.txt from Docker Hub and saves all of the images as rancher-images.tar.gz.
    rancher-load-images.shThis script loads images from the rancher-images.tar.gz file and pushes them to your private registry.

    2. Collect the cert-manager image​

    Skip this step if you are using your own certificates, or if you are terminating TLS on an external load balancer.

    In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS certificates, you must add the cert-manager image to rancher-images.txt as well.

    1. Fetch the latest cert-manager Helm chart and parse the template for image details:

      Note: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.12.0, please see our upgrade documentation.

      helm repo add jetstack https://charts.jetstack.io
      helm repo update
      helm fetch jetstack/cert-manager --version v1.5.1
      helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt

    2. Sort and unique the images list to remove any overlap between the sources:

      sort -u rancher-images.txt -o rancher-images.txt

    3. Save the images to your workstation​

    1. Make rancher-save-images.sh an executable:

      chmod +x rancher-save-images.sh

    2. Run rancher-save-images.sh with the rancher-images.txt image list to create a tarball of all the required images:

      ./rancher-save-images.sh --image-list ./rancher-images.txt

      Result: Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named rancher-images.tar.gz. Check that the output is in the directory.

    4. Populate the private registry​

    Next, you will move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

    Move the images in the rancher-images.tar.gz to your private registry using the scripts to load the images.

    The rancher-images.txt is expected to be on the workstation in the same directory that you are running the rancher-load-images.sh script. The rancher-images.tar.gz should also be in the same directory.

    1. Log into your private registry if required:

      docker login <REGISTRY.YOURDOMAIN.COM:PORT>

    2. Make rancher-load-images.sh an executable:

      chmod +x rancher-load-images.sh

    3. Use rancher-load-images.sh to extract, tag and push rancher-images.txt and rancher-images.tar.gz to your private registry:

      ./rancher-load-images.sh --image-list ./rancher-images.txt --registry <REGISTRY.YOURDOMAIN.COM:PORT>

    Next step for Kubernetes Installs - Launch a Kubernetes Cluster​

    Next step for Docker Installs - Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/roll-back-rancherd.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/roll-back-rancherd.html index 721c482bd96..7382b76d117 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/roll-back-rancherd.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/roll-back-rancherd.html @@ -5,13 +5,13 @@ Rollbacks | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.html index f27f2409fbf..7f23009a965 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/install-rancher-on-linux/upgrade-rancherd.html @@ -5,13 +5,13 @@ Upgrades | Rancher Manager - +
    Version: v2.5

    Upgrades

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    When RancherD is upgraded, the Rancher Helm controller and the Fleet pods are upgraded.

    During a RancherD upgrade, there is very little downtime, but it is possible that RKE2 may be down for a minute, during which you could lose access to Rancher.

    When Rancher is installed with RancherD, the underlying Kubernetes cluster can't be upgraded from the Rancher UI. It needs to be upgraded using the RancherD CLI.

    Upgrading the Rancher Helm Chart without Upgrading the Underlying Cluster​

    To upgrade Rancher without upgrading the underlying Kubernetes cluster, follow these steps.

    Before upgrading, we recommend that you should:

    • Create a backup of the Rancher server using the backup application.
    • Review the known issues for the Rancher version you are upgrading to. The known issues are listed in the release notes on GitHub and on the Rancher forums.

    1. Uninstall the chart with Helm:

      helm uninstall rancher

    2. Reinstall the Rancher chart with Helm. To install a specific Rancher version, use the --version flag. For example:

      helm install rancher rancher-latest/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --version 2.5.1

    Result: Rancher is upgraded to the new version.

    If necessary, restore Rancher from backup by following these steps.

    Upgrading Both Rancher and the Underlying Cluster​

    Upgrade both RancherD and the underlying Kubernetes cluster by re-running the RancherD installation script.

    Before upgrading, we recommend that you should:

    • Create a backup of the Rancher server using the backup application.
    • Review the known issues for the Rancher version you are upgrading to. The known issues are listed in the release notes on GitHub and on the Rancher forums.
    sudo curl -sfL https://get.rancher.io | sudo sh -

    To specify a specific version to upgrade to, use INSTALL_RANCHERD_VERSION environment variable:

    curl -sfL https://get.rancher.io | INSTALL_RANCHERD_VERSION=v2.5.1 sh -

    Then launch the server:

    systemctl enable rancherd-server
    systemctl start rancherd-server

    The upgrade can also be performed by manually installing the binary of the desired version.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html index 1f86db4e645..7b6195bb656 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.html @@ -5,14 +5,14 @@ 2. Install Kubernetes | Rancher Manager - +
    Version: v2.5

    2. Install Kubernetes

    Once the infrastructure is ready, you can continue with setting up an RKE cluster to install Rancher in.

    Installing Docker​

    First, you have to install Docker and setup the HTTP proxy on all three Linux nodes. For this perform the following steps on all three nodes.

    For convenience export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell:

    export proxy_host="10.0.0.5:8888"
    export HTTP_PROXY=http://${proxy_host}
    export HTTPS_PROXY=http://${proxy_host}
    export NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16

    Next configure apt to use this proxy when installing packages. If you are not using Ubuntu, you have to adapt this step accordingly:

    cat <<EOF | sudo tee /etc/apt/apt.conf.d/proxy.conf > /dev/null
    Acquire::http::Proxy "http://${proxy_host}/";
    Acquire::https::Proxy "http://${proxy_host}/";
    EOF

    Now you can install Docker:

    curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh

    Then ensure that your current user is able to access the Docker daemon without sudo:

    sudo usermod -aG docker YOUR_USERNAME

    And configure the Docker daemon to use the proxy to pull images:

    sudo mkdir -p /etc/systemd/system/docker.service.d
    cat <<EOF | sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null
    [Service]
    Environment="HTTP_PROXY=http://${proxy_host}"
    Environment="HTTPS_PROXY=http://${proxy_host}"
    Environment="NO_PROXY=127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"
    EOF

    To apply the configuration, restart the Docker daemon:

    sudo systemctl daemon-reload
    sudo systemctl restart docker

    Creating the RKE Cluster​

    You need several command line tools on the host where you have SSH access to the Linux nodes to create and interact with the cluster:

    sudo curl -fsSL -o /usr/local/bin/rke https://github.com/rancher/rke/releases/download/v1.1.4/rke_linux-amd64
    sudo chmod +x /usr/local/bin/rke
    curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
    chmod +x ./kubectl
    sudo mv ./kubectl /usr/local/bin/kubectl
    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
    chmod +x get_helm.sh
    sudo ./get_helm.sh

    Next, create a YAML file that describes the RKE cluster. Ensure that the IP addresses of the nodes and the SSH username are correct. For more information on the cluster YAML, have a look at the RKE documentation.

    nodes:
      - address: 10.0.1.200
        user: ubuntu
        role: [controlplane,worker,etcd]
      - address: 10.0.1.201
        user: ubuntu
        role: [controlplane,worker,etcd]
      - address: 10.0.1.202
        user: ubuntu
        role: [controlplane,worker,etcd]

    services:
      etcd:
        backup_config:
          interval_hours: 12
          retention: 6

    After that, you can create the Kubernetes cluster by running:

    rke up --config rancher-cluster.yaml

    RKE creates a state file called rancher-cluster.rkestate, this is needed if you want to perform updates, modify your cluster configuration or restore it from a backup. It also creates a kube_config_cluster.yaml file, that you can use to connect to the remote Kubernetes cluster locally with tools like kubectl or Helm. Make sure to save all of these files in a secure location, for example by putting them into a version control system.

    To have a look at your cluster run:

    export KUBECONFIG=kube_config_cluster.yaml
    kubectl cluster-info
    kubectl get pods --all-namespaces

    You can also verify that your external load balancer works, and the DNS entry is set up correctly. If you send a request to either, you should receive HTTP 404 response from the ingress controller:

    $ curl 10.0.1.100
    default backend - 404
    $ curl rancher.example.com
    default backend - 404

    Save Your Files​

    Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

    Save a copy of the following files in a secure location:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
    • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains the current state of the cluster including the RKE configuration and the certificates.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html index 33db09259f4..5d41c1696b6 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.html @@ -5,13 +5,13 @@ 3. Install Rancher | Rancher Manager - +
    Version: v2.5

    3. Install Rancher

    Now that you have a running RKE cluster, you can install Rancher in it. For security reasons all traffic to Rancher must be encrypted with TLS. For this tutorial you are going to automatically issue a self-signed certificate through cert-manager. In a real-world use-case you will likely use Let's Encrypt or provide your own certificate.

    Note: These installation instructions assume you are using Helm 3.

    Install cert-manager​

    Add the cert-manager helm repository:

    helm repo add jetstack https://charts.jetstack.io

    Create a namespace for cert-manager:

    kubectl create namespace cert-manager

    Install the CustomResourceDefinitions of cert-manager:

    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml

    And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:

    helm upgrade --install cert-manager jetstack/cert-manager \
      --namespace cert-manager --version v1.5.1 \
      --set http_proxy=http://${proxy_host} \
      --set https_proxy=http://${proxy_host} \
      --set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local

    Now you should wait until cert-manager is finished starting up:

    kubectl rollout status deployment -n cert-manager cert-manager
    kubectl rollout status deployment -n cert-manager cert-manager-webhook

    Install Rancher​

    Next you can install Rancher itself. First add the helm repository:

    helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

    Create a namespace:

    kubectl create namespace cattle-system

    And install Rancher with Helm. Rancher also needs a proxy configuration so that it can communicate with external application catalogs or retrieve Kubernetes version update metadata.

    Note that rancher.cattle-system must be added to the noProxy list (as shown below) so that Fleet can communicate directly to Rancher with Kubernetes service DNS using service discovery.

    helm upgrade --install rancher rancher-latest/rancher \
       --namespace cattle-system \
       --set hostname=rancher.example.com \
       --set proxy=http://${proxy_host}
       --set noProxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local,rancher.cattle-system

    After waiting for the deployment to finish:

    kubectl rollout status deployment -n cattle-system rancher

    You can now navigate to https://rancher.example.com and start using Rancher.

    Note: If you don't intend to send telemetry data, opt out telemetry during the initial login. Leaving this active in an air-gapped environment can cause issues if the sockets cannot be opened successfully.

    Additional Resources​

    These resources could be helpful when installing Rancher:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html index 14659879687..f6efcecbcf0 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/set-up-infrastructure.html @@ -5,14 +5,14 @@ 1. Set up Infrastructure | Rancher Manager - +
    Version: v2.5

    1. Set up Infrastructure

    In this section, you will provision the underlying infrastructure for your Rancher management server with internete access through a HTTP proxy.

    To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
    • A load balancer to direct front-end traffic to the three nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    These nodes must be in the same region/data center. You may place these servers in separate availability zones.

    Why three nodes?​

    In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

    The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

    1. Set up Linux Nodes​

    These hosts will connect to the internet through an HTTP proxy.

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    3. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Next: Set up a Kubernetes cluster​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html index f8d3f48dc34..079a7d4a4c8 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/certificate-troubleshooting.html @@ -5,14 +5,14 @@ Certificate Troubleshooting | Rancher Manager - +
    Version: v2.5

    Certificate Troubleshooting

    How Do I Know if My Certificates are in PEM Format?​

    You can recognize the PEM format by the following traits:

    • The file begins with the following header:
      -----BEGIN CERTIFICATE-----
    • The header is followed by a long string of characters.
    • The file ends with a footer: -----END CERTIFICATE-----

    PEM Certificate Example:

    ----BEGIN CERTIFICATE-----
    MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
    ... more lines
    VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
    -----END CERTIFICATE-----

    PEM Certificate Key Example:

    -----BEGIN RSA PRIVATE KEY-----
    MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
    ... more lines
    VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
    -----END RSA PRIVATE KEY-----

    If your key looks like the example below, see Converting a Certificate Key From PKCS8 to PKCS1.

    -----BEGIN PRIVATE KEY-----
    MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
    ... more lines
    VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
    -----END PRIVATE KEY-----

    Converting a Certificate Key From PKCS8 to PKCS1​

    If you are using a PKCS8 certificate key file, Rancher will log the following line:

    ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})

    To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:

    openssl rsa -in key.pem -out convertedkey.pem

    You can now use convertedkey.pem as certificate key file for Rancher.

    What is the Order of Certificates if I Want to Add My Intermediate(s)?​

    The order of adding certificates is as follows:

    -----BEGIN CERTIFICATE-----
    %YOUR_CERTIFICATE%
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    %YOUR_INTERMEDIATE_CERTIFICATE%
    -----END CERTIFICATE-----

    How Do I Validate My Certificate Chain?​

    You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. The ca.pem file must be the same as you added to the rancher/rancher container.

    When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

    Command:

    openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
    ...
        Verify return code: 0 (ok)
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html index 56957b306fd..4e0a274ecbf 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/roll-back-docker-installed-rancher.html @@ -5,13 +5,13 @@ Rolling Back Rancher Installed with Docker | Rancher Manager - +
    Version: v2.5

    Rolling Back Rancher Installed with Docker

    If a Rancher upgrade does not complete successfully, you'll have to roll back to your Rancher setup that you were using before Docker Upgrade. Rolling back restores:

    • Your previous version of Rancher.
    • Your data backup created before upgrade.

    Before You Start​

    During rollback to a prior version of Rancher, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

    In this command, <PRIOR_RANCHER_VERSION> is the version of Rancher you were running before your unsuccessful upgrade. v2.0.5 for example.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME>![Placeholder Reference](/img/placeholder-ref-2.png)
    PlaceholderExampleDescription
    <PRIOR_RANCHER_VERSION>v2.0.5The rancher/rancher image you used before upgrade.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version of Rancher that the backup is for.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <PRIOR_RANCHER_VERSION> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

    Rolling Back Rancher​

    If you have issues upgrading Rancher, roll it back to its latest known healthy state by pulling the last version you used and then restoring the backup you made before upgrade.

    Warning! Rolling back to a previous version of Rancher destroys any changes made to Rancher following the upgrade. Unrecoverable data loss may occur.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Pull the version of Rancher that you were running before upgrade. Replace the <PRIOR_RANCHER_VERSION> with that version.

      For example, if you were running Rancher v2.0.5 before upgrade, pull v2.0.5.

      docker pull rancher/rancher:<PRIOR_RANCHER_VERSION>

    3. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>

      You can obtain the name for your Rancher container by entering docker ps.

    4. Move the backup tarball that you created during completion of Docker Upgrade onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

      If you followed the naming convention we suggested in Docker Upgrade, it will have a name similar to (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

    5. Run the following command to replace the data in the rancher-data container with the data in the backup tarball, replacing the placeholder. Don't forget to close the quotes.

      docker run  --volumes-from rancher-data \
      -v $PWD:/backup busybox sh -c "rm /var/lib/rancher/* -rf \
      && tar zxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

    6. Start a new Rancher Server container with the <PRIOR_RANCHER_VERSION> tag placeholder pointing to the data container.

      docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:<PRIOR_RANCHER_VERSION>

      As of Rancher v2.5, privileged access is required.

      Note: Do not stop the rollback after initiating it, even if the rollback process seems longer than expected. Stopping the rollback may result in database issues during future upgrades.

    7. Wait a few moments and then open Rancher in a web browser. Confirm that the rollback succeeded and that your data is restored.

    Result: Rancher is rolled back to its version and data state before upgrade.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html index f60438106c1..3285153cd5b 100644 --- a/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html +++ b/v2.5/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.html @@ -5,13 +5,13 @@ Upgrading Rancher Installed with Docker | Rancher Manager - +
    Version: v2.5

    Upgrading Rancher Installed with Docker

    The following instructions will guide you through upgrading a Rancher server that was installed with Docker.

    Prerequisites

    Placeholder Review

    During upgrade, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>).

    Here's an example of a command with a placeholder:

    docker stop <RANCHER_CONTAINER_NAME>

    In this command, <RANCHER_CONTAINER_NAME> is the name of your Rancher container.

    Get Data for Upgrade Commands

    To obtain the data to replace the placeholders, run:

    docker ps

    Write down or copy this information before starting the upgrade.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.1.3The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.1.3The version of Rancher that you're creating a backup for.
    <DATE>2018-12-19The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

    Upgrade Outline

    During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data. Follow the steps to upgrade Rancher server:

    1. Create a copy of the data from your Rancher server container

    1. Using a remote Terminal connection, log into the node running your Rancher server.

    2. Stop the container currently running Rancher server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>
    3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
      docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data rancher/rancher:<RANCHER_CONTAINER_TAG>

    2. Create a backup tarball

    1. From the data container that you just created (rancher-data), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz).

      This tarball will serve as a rollback point if something goes wrong during upgrade. Use the following command, replacing each placeholder.

    ```
    docker run --volumes-from rancher-data -v "$PWD:/backup" --rm busybox tar zcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
    ```

    **Step Result:** When you enter this command, a series of commands should run.

    1. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

      [rancher@ip-10-0-0-50 ~]$ ls
      rancher-data-backup-v2.1.3-20181219.tar.gz

    2. Move your backup tarball to a safe location external from your Rancher server.

    3. Pull the New Docker Image

    Pull the image of the Rancher version that you want to upgrade to.

    PlaceholderDescription
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
    docker pull rancher/rancher:<RANCHER_VERSION_TAG>

    4. Start the New Rancher Server Container

    Start a new Rancher server container using the data from the rancher-data container. Remember to pass in all the environment variables that you had used when you started the original container.

    Important: Do not stop the upgrade after initiating it, even if the upgrade process seems longer than expected. Stopping the upgrade may result in database migration errors during future upgrades.

    If you used a proxy, see HTTP Proxy Configuration.

    If you configured a custom CA root certificate to access your services, see Custom CA root certificate.

    If you are recording all transactions with the Rancher API, see API Auditing

    To see the command to use when starting the new Rancher server container, choose from the following options:

    • Docker Upgrade
    • Docker Upgrade for Air Gap Installs

    Select which option you had installed Rancher server

    Option A: Default Self-Signed Certificate​

    Click to expand

    If you have selected to use the Rancher generated self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container.

    PlaceholderDescription
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
    docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:<RANCHER_VERSION_TAG>

    As of Rancher v2.5, privileged access is required.

    Option B: Bring Your Own Certificate: Self-Signed​

    Click to expand

    If you have selected to bring your own self-signed certificate, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificate that you had originally installed with.

    Reminder of the Cert Prerequisite: The certificate files must be in PEM format. In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <CA_CERTS.pem>The path to the certificate authority's certificate.
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
    docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
      --privileged \
      rancher/rancher:<RANCHER_VERSION_TAG>

    As of Rancher v2.5, privileged access is required.

    Option C: Bring Your Own Certificate: Signed by Recognized CA​

    Click to expand

    If you have selected to use a certificate signed by a recognized CA, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to have access to the same certificates that you had originally installed with. Remember to include --no-cacerts as an argument to the container to disable the default CA certificate generated by Rancher.

    Reminder of the Cert Prerequisite: The certificate files must be in PEM format. In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
    docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      --privileged \
      rancher/rancher:<RANCHER_VERSION_TAG> \
      --no-cacerts

    As of Rancher v2.5, privileged access is required.

    Option D: Let's Encrypt Certificate​

    Click to expand

    Remember: Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

    If you have selected to use Let's Encrypt certificates, you add the --volumes-from rancher-data to the command that you had started your original Rancher server container and need to provide the domain that you had used when you originally installed Rancher.

    Reminder of the Cert Prerequisites:

    • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
    • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.
    PlaceholderDescription
    <RANCHER_VERSION_TAG>The release tag of the Rancher version that you want to upgrade to.
    <YOUR.DNS.NAME>The domain address that you had originally started with
    docker run -d --volumes-from rancher-data \
      --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:<RANCHER_VERSION_TAG> \
      --acme-domain <YOUR.DNS.NAME>

    As of Rancher v2.5, privileged access is required.

    Result: You have upgraded Rancher. Data from your upgraded server is now saved to the rancher-data container for use in future upgrades.

    5. Verify the Upgrade

    Log into Rancher. Confirm that the upgrade succeeded by checking the version displayed in the bottom-left corner of the browser window.

    Having network issues in your user clusters following upgrade?

    See Restoring Cluster Networking.

    6. Clean up Your Old Rancher Server Container

    Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.

    Rolling Back

    If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see Docker Rollback.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.html b/v2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.html index 000e0afbd19..83442589dc7 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/add-tls-secrets.html @@ -5,14 +5,14 @@ Adding TLS Secrets | Rancher Manager - +
    Version: v2.5

    Adding TLS Secrets

    Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the tls-rancher-ingress secret in the cattle-system namespace with the certificate and key.

    Combine the server certificate followed by any intermediate certificate(s) needed into a file named tls.crt. Copy your certificate key into a file named tls.key.

    For example, acme.sh provides server certificate and CA chains in fullchain.cer file. This fullchain.cer should be renamed to tls.crt & certificate key file as tls.key.

    Use kubectl with the tls secret type to create the secrets.

    kubectl -n cattle-system create secret tls tls-rancher-ingress \
      --cert=tls.crt \
      --key=tls.key

    Note: If you want to replace the certificate, you can delete the tls-rancher-ingress secret using kubectl -n cattle-system delete secret tls-rancher-ingress and add a new one using the command shown above. If you are using a private CA signed certificate, replacing the certificate is only possible if the new certificate is signed by the same CA as the certificate currently in use.

    Using a Private CA Signed Certificate

    If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server.

    Copy the CA certificate into a file named cacerts.pem and use kubectl to create the tls-ca secret in the cattle-system namespace.

    kubectl -n cattle-system create secret generic tls-ca \
      --from-file=cacerts.pem=./cacerts.pem

    Note: The configured tls-ca secret is retrieved when Rancher starts. On a running Rancher installation the updated CA will take effect after new Rancher pods are started.

    Updating a Private CA Certificate

    Follow the steps on this page to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html b/v2.5/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html index 1ca68e0ccce..2b870d48a2c 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/choose-a-rancher-version.html @@ -5,7 +5,7 @@ Choosing a Rancher Version | Rancher Manager - + @@ -14,7 +14,7 @@     helm search repo --versions

    If you have several repos you can specify the repo name, ie. helm search repo rancher-stable/rancher --versions
    For more information, see https://helm.sh/docs/helm/helm_search_repo/

    To fetch a specific version of your chosen repo, define the --version parameter like in the following example:
        helm fetch rancher-stable/rancher --version=2.4.8

    Switching to a Different Helm Chart Repository​

    After installing Rancher, if you want to change which Helm chart repository to install Rancher from, you will need to follow these steps.

    Note: Because the rancher-alpha repository contains only alpha charts, switching between the rancher-alpha repository and the rancher-stable or rancher-latest repository for upgrades is not supported.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      Note: Upgrades are not supported to, from, or between Alphas.

    1. List the current Helm chart repositories.

      helm repo list

      NAME                  URL
      stable                https://charts.helm.sh/stable
      rancher-<CHART_REPO>        https://releases.rancher.com/server-charts/<CHART_REPO>

    2. Remove the existing Helm Chart repository that contains your charts to install Rancher, which will either be rancher-stable or rancher-latest depending on what you had initially added.

      helm repo remove rancher-<CHART_REPO>

    3. Add the Helm chart repository that you want to start installing Rancher from.

      helm repo add rancher-<CHART_REPO> https://releases.rancher.com/server-charts/<CHART_REPO>

    4. Continue to follow the steps to upgrade Rancher from the new Helm chart repository.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html b/v2.5/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html index 5bb8b7b3c33..d984d97f2a6 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/custom-ca-root-certificates.html @@ -5,13 +5,13 @@ About Custom CA Root Certificates | Rancher Manager - +
    Version: v2.5

    About Custom CA Root Certificates

    If you're using Rancher in an internal production environment where you aren't exposing apps publicly, use a certificate from a private certificate authority (CA).

    Services that Rancher needs to access are sometimes configured with a certificate from a custom/internal CA root, also known as self signed certificate. If the presented certificate from the service cannot be validated by Rancher, the following error displays: x509: certificate signed by unknown authority.

    To validate the certificate, the CA root certificates need to be added to Rancher. As Rancher is written in Go, we can use the environment variable SSL_CERT_DIR to point to the directory where the CA root certificates are located in the container. The CA root certificates directory can be mounted using the Docker volume option (-v host-source-directory:container-destination-directory) when starting the Rancher container.

    Examples of services that Rancher can access:

    • Catalogs
    • Authentication providers
    • Accessing hosting/cloud API when using Node Drivers

    Installing with the custom CA Certificate​

    For details on starting a Rancher container with your private CA certificates mounted, refer to the installation docs:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/helm-version-requirements.html b/v2.5/getting-started/installation-and-upgrade/resources/helm-version-requirements.html index af4be6f7f14..bf12e285081 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/helm-version-requirements.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/helm-version-requirements.html @@ -5,13 +5,13 @@ Helm Version Requirements | Rancher Manager - +
    Version: v2.5

    Helm Version Requirements

    This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.

    The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 Migration Docs. This section provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

    • Helm v3.2.x or higher is required to install or upgrade Rancher v2.5.
    • Helm v2.16.0 or higher is required for Kubernetes v1.16. For the default Kubernetes version, refer to the release notes for the version of RKE that you are using.
    • Helm v2.15.0 should not be used, because of an issue with converting/comparing numbers.
    • Helm v2.12.0 should not be used, because of an issue with cert-manager.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/local-system-charts.html b/v2.5/getting-started/installation-and-upgrade/resources/local-system-charts.html index 859afdb746d..33d110f5fff 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/local-system-charts.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/local-system-charts.html @@ -5,13 +5,13 @@ Setting up Local System Charts for Air Gapped Installations | Rancher Manager - +
    Version: v2.5

    Setting up Local System Charts for Air Gapped Installations

    The System Charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS.

    In an air gapped installation of Rancher, you will need to configure Rancher to use a local copy of the system charts. This section describes how to use local system charts using a CLI flag.

    Using Local System Charts

    A local copy of system-charts has been packaged into the rancher/rancher container. To be able to use these features in an air gap install, you will need to run the Rancher install command with an extra environment variable, CATTLE_SYSTEM_CATALOG=bundled, which tells Rancher to use the local copy of the charts instead of attempting to fetch them from GitHub.

    Example commands for a Rancher installation with a bundled system-charts are included in the air gap Docker installation instructions and the air gap Kubernetes installation instructions.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html b/v2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html index 5916c156b02..218856ee8c9 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/update-rancher-certificate.html @@ -5,14 +5,14 @@ Updating the Rancher Certificate | Rancher Manager - +
    Version: v2.5

    Updating a Private CA Certificate

    Follow these steps to update the SSL certificate of the ingress in a Rancher high availability Kubernetes installation or to switch from the default self-signed certificate to a custom certificate.

    A summary of the steps is as follows:

    1. Create or update the tls-rancher-ingress Kubernetes secret resource with the new certificate and private key.
    2. Create or update the tls-ca Kubernetes secret resource with the root CA certificate (only required when using a private CA).
    3. Update the Rancher installation using the Helm CLI.
    4. Reconfigure the Rancher agents to trust the new CA certificate.
    5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher.

    The details of these instructions are below.

    1. Create/update the certificate secret resource​

    First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

    If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

    $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
      --cert=tls.crt \
      --key=tls.key

    Alternatively, to update an existing certificate secret:

    $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
      --cert=tls.crt \
      --key=tls.key \
      --dry-run --save-config -o yaml | kubectl apply -f -

    2. Create/update the CA certificate secret resource​

    If the new certificate was signed by a private CA, you will need to copy the corresponding root CA certificate into a file named cacerts.pem and create or update the tls-ca secret in the cattle-system namespace. If the certificate was signed by an intermediate CA, then the cacerts.pem must contain both the intermediate and root CA certificates (in this order).

    To create the initial secret:

    $ kubectl -n cattle-system create secret generic tls-ca \
      --from-file=cacerts.pem

    To update an existing tls-ca secret:

    $ kubectl -n cattle-system create secret generic tls-ca \
      --from-file=cacerts.pem \
      --dry-run --save-config -o yaml | kubectl apply -f -

    3. Reconfigure the Rancher deployment​

    Before proceeding, generate an API token in the Rancher UI (User > API & Keys) and save the Bearer Token which you might need in step 4.

    This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

    It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

    To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

    $ helm get values rancher -n cattle-system

    Also get the version string of the currently deployed Rancher chart:

    $ helm ls -A

    Upgrade the Helm application instance using the original configuration values and making sure to specify ingress.tls.source=secret as well as the current chart version to prevent an application upgrade.

    If the certificate was signed by a private CA, add the set privateCA=true argument as well. Also make sure to read the documentation describing the initial installation using custom certificates.

    helm upgrade rancher rancher-stable/rancher \
      --namespace cattle-system \
      --version <DEPLOYED_CHART_VERSION> \
      --set hostname=rancher.my.org \
      --set ingress.tls.source=secret \
      --set ...

    When the upgrade is completed, navigate to https://<Rancher_SERVER>/v3/settings/cacerts to verify that the value matches the CA certificate written in the tls-ca secret earlier.

    4. Reconfigure Rancher agents to trust the private CA​

    This section covers three methods to reconfigure Rancher agents to trust the private CA. This step is required if either of the following is true:

    • Rancher was initially configured to use the Rancher self-signed certificate (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt)
    • The root CA certificate for the new custom certificate has changed

    Why is this step required?​

    When Rancher is configured with a certificate signed by a private CA, the CA certificate chain is downloaded into Rancher agent containers. Agents compare the checksum of the downloaded certificate against the CATTLE_CA_CHECKSUM environment variable. This means that, when the private CA certificate is changed on Rancher server side, the environvment variable CATTLE_CA_CHECKSUM must be updated accordingly.

    Which method should I choose?​

    Method 1 is the easiest one but requires all clusters to be connected to Rancher after the certificates have been rotated. This is usually the case if the process is performed right after updating the Rancher deployment (Step 3).

    If the clusters have lost connection to Rancher but you have Authorized Cluster Endpoints enabled, then go with method 2.

    Method 3 can be used as a fallback if method 1 and 2 are unfeasible.

    Method 1: Kubectl command​

    For each cluster under Rancher management (except the local Rancher management cluster) run the following command using the Kubeconfig file of the Rancher management cluster (RKE or K3S).

    kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge

    This command will cause all Agent Kubernetes resources to be reconfigured with the checksum of the new certificate.

    Method 2: Manually update checksum​

    Manually patch the agent Kubernetes resources by updating the CATTLE_CA_CHECKSUM environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:

    $ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
    $ sha256sum cacert.tmp | awk '{print $1}'

    Using a Kubeconfig for each downstream cluster update the environment variable for the two agent deployments.

    $ kubectl edit -n cattle-system ds/cattle-node-agent
    $ kubectl edit -n cattle-system deployment/cattle-cluster-agent

    Method 3: Recreate Rancher agents​

    With this method you are recreating the Rancher agents by running a set of commands on a controlplane node of each downstream cluster.

    First, generate the agent definitions as described here: https://gist.github.com/superseb/076f20146e012f1d4e289f5bd1bd4971

    Then, connect to a controlplane node of the downstream cluster via SSH, create a Kubeconfig and apply the definitions: https://gist.github.com/superseb/b14ed3b5535f621ad3d2aa6a4cd6443b

    5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher​

    Select 'Force Update' for the clusters within the Continuous Delivery view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

    Why is this step required?​

    Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.

    Updating from a Private CA Certificate to a Common Certificate

    It is possible to perform the opposite procedure as shown above: you may change from a private certificate to a common, or non-private, certificate. The steps involved are outlined below.

    1. Create/update the certificate secret resource​

    First, concatenate the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.

    If you are switching the install from using the Rancher self-signed certificate or Let’s Encrypt issued certificates, use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:

    $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
      --cert=tls.crt \
      --key=tls.key

    Alternatively, to update an existing certificate secret:

    $ kubectl -n cattle-system create secret tls tls-rancher-ingress \
      --cert=tls.crt \
      --key=tls.key \
      --dry-run --save-config -o yaml | kubectl apply -f -

    2. Delete the CA certificate secret resource​

    You will delete the tls-ca secret in the cattle-system namespace as it is no longer needed. You may also optionally save a copy of the tls-ca secret if desired.

    To save the existing secret:

    kubectl -n cattle-system get secret tls-ca -o yaml > tls-ca.yaml

    To delete the existing tls-ca secret:

    kubectl -n cattle-system delete secret tls-ca

    3. Reconfigure the Rancher deployment​

    Before proceeding, generate an API token in the Rancher UI (User > API & Keys).

    This step is required if Rancher was initially installed with self-signed certificates (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).

    It ensures that the Rancher pods and ingress resources are reconfigured to use the new server and optional CA certificate.

    To update the Helm deployment you will need to use the same (--set) options that were used during initial installation. Check with:

    $ helm get values rancher -n cattle-system

    Also get the version string of the currently deployed Rancher chart:

    $ helm ls -A

    Upgrade the Helm application instance using the original configuration values and making sure to specify the current chart version to prevent an application upgrade.

    Also make sure to read the documentation describing the initial installation using custom certificates.

    helm upgrade rancher rancher-stable/rancher \
      --namespace cattle-system \
      --version <DEPLOYED_CHART_VERSION> \
      --set hostname=rancher.my.org \
      --set ...

    On upgrade, you can either

    • remove --set ingress.tls.source=secret \ from the Helm upgrade command, as shown above, or

    • remove the privateCA parameter or set it to false because the CA is valid:

    set privateCA=false

    4. Reconfigure Rancher agents for the non-private/common certificate​

    CATTLE_CA_CHECKSUM environment variable on the downstream cluster agents should be removed or set to "" (an empty string).

    5. Select Force Update of Fleet clusters to connect fleet-agent to Rancher​

    Select 'Force Update' for the clusters within the Continuous Delivery view under Cluster Explorer in the Rancher UI to allow the fleet-agent in downstream clusters to successfully connect to Rancher.

    Why is this step required?​

    Fleet agents in Rancher managed clusters store kubeconfig that is used to connect to the Rancher proxied kube-api in the fleet-agent secret of the fleet-system namespace. The kubeconfig contains a certificate-authority-data block containing the Rancher CA. When changing the Rancher CA, this block needs to be updated for a successful connection of the fleet-agent to Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html b/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html index 09c558c3706..0d95266f2d1 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2.html @@ -5,7 +5,7 @@ Upgrading Cert-Manager with Helm 2 | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Upgrading Cert-Manager with Helm 2

    Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:

    1. Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.
    2. Cert-manager is deprecating and replacing the certificate.spec.acme.solvers field. This change has no exact deadline.
    3. Cert-manager is deprecating v1alpha1 API and replacing its API group

    To address these changes, this guide will do two things:

    1. Document the procedure for upgrading cert-manager
    2. Explain the cert-manager API changes and link to cert-manager's offficial documentation for migrating your data

    Important: If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, you need to reinstall both of them:

    1. Take a one-time snapshot of your Kubernetes cluster running Rancher server
    2. Uninstall Rancher, cert-manager, and the CustomResourceDefinition for cert-manager
    3. Install the newer version of Rancher and cert-manager

    The reason is that when Helm upgrades Rancher, it will reject the upgrade and show error messages if the running Rancher app does not match the chart template used to install it. Because cert-manager changed its API group and we cannot modify released charts for Rancher, there will always be a mismatch on the cert-manager's API version, therefore the upgrade will be rejected.

    For reinstalling Rancher with Helm, please check Option B: Reinstalling Rancher Chart under the upgrade Rancher section.

    Upgrade Cert-Manager Only​

    Note: These instructions are applied if you have no plan to upgrade Rancher.

    The namespace used in these instructions depends on the namespace cert-manager is currently installed in. If it is in kube-system use that in the instructions below. You can verify by running kubectl get pods --all-namespaces and checking which namespace the cert-manager-* pods are listed in. Do not change the namespace cert-manager is running in or this can cause issues.

    In order to upgrade cert-manager, follow these instructions:

    Upgrading cert-manager with Internet access

    1. Back up existing resources as a precaution

      kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml

    2. Delete the existing deployment

      helm delete --purge cert-manager

    3. Install the CustomResourceDefinition resources separately

      kubectl apply -f https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml

    4. Add the Jetstack Helm repository

      helm repo add jetstack https://charts.jetstack.io

    5. Update your local Helm chart repository cache

      helm repo update

    6. Install the new version of cert-manager

      helm install --version 0.12.0 --name cert-manager --namespace kube-system jetstack/cert-manager
    Upgrading cert-manager in an airgapped environment

    Prerequisites​

    Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.

    1. Follow the guide to Prepare your Private Registry with the images needed for the upgrade.

    2. From a system connected to the internet, add the cert-manager repo to Helm

      helm repo add jetstack https://charts.jetstack.io
      helm repo update

    3. Fetch the latest cert-manager chart available from the Helm chart repository.

      helm fetch jetstack/cert-manager --version v0.12.0

    4. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

      helm template ./cert-manager-v0.12.0.tgz --output-dir . \
      --name cert-manager --namespace kube-system \
      --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
      --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
      --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

    5. Download the required CRD file for cert-manager

      curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml

    Install cert-manager​

    1. Back up existing resources as a precaution

      kubectl get -o yaml --all-namespaces issuer,clusterissuer,certificates > cert-manager-backup.yaml

    2. Delete the existing cert-manager installation

      kubectl -n kube-system delete deployment,sa,clusterrole,clusterrolebinding -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

    3. Install the CustomResourceDefinition resources separately

      kubectl apply -f cert-manager/cert-manager-crd.yaml

    1. Install cert-manager

      kubectl -n kube-system apply -R -f ./cert-manager

    Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:

    kubectl get pods --namespace kube-system

    NAME                                            READY   STATUS      RESTARTS   AGE
    cert-manager-7cbdc48784-rpgnt                   1/1     Running     0          3m
    cert-manager-webhook-5b5dd6999-kst4x            1/1     Running     0          3m
    cert-manager-cainjector-3ba5cd2bcd-de332x       1/1     Running     0          3m

    If the ‘webhook’ pod (2nd line) is in a ContainerCreating state, it may still be waiting for the Secret to be mounted into the pod. Wait a couple of minutes for this to happen but if you experience problems, please check cert-manager's troubleshooting guide.

    Note: The above instructions ask you to add the disable-validation label to the kube-system namespace. Here are additional resources that explain why this is necessary:

    Cert-Manager API change and data migration​

    Cert-manager has deprecated the use of the certificate.spec.acme.solvers field and will drop support for it completely in an upcoming release.

    Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.

    Details about the change and migration instructions can be found in the cert-manager v0.7 to v0.8 upgrade instructions.

    The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.

    We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the upgrading to v0.8 guide.

    Details about the change and migration instructions can be found in the cert-manager v0.10 to v0.11 upgrade instructions.

    For information on upgrading from all other versions of cert-manager, refer to the official documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html b/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html index 8b1064850ca..e2c821d5b64 100644 --- a/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html +++ b/v2.5/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.html @@ -5,7 +5,7 @@ Upgrading Cert-Manager | Rancher Manager - + @@ -16,7 +16,7 @@ If you are upgrading from a version older than 0.11.0, Update the apiVersion on If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

  • Create the namespace for cert-manager if needed

    kubectl create namespace cert-manager

  • Add the Jetstack Helm repository

    helm repo add jetstack https://charts.jetstack.io

  • Update your local Helm chart repository cache

    helm repo update

  • Install the new version of cert-manager

    helm install \
      cert-manager jetstack/cert-manager \
      --namespace cert-manager \
      --version v0.12.0

  • Restore back up resources

    kubectl apply -f cert-manager-backup.yaml

    • Option B: Upgrade cert-manager in an Air Gap Environment​

    Click to expand

    Prerequisites​

    Before you can perform the upgrade, you must prepare your air gapped environment by adding the necessary container images to your private registry and downloading or rendering the required Kubernetes manifest files.

    1. Follow the guide to Prepare your Private Registry with the images needed for the upgrade.

    2. From a system connected to the internet, add the cert-manager repo to Helm

      helm repo add jetstack https://charts.jetstack.io
      helm repo update

    3. Fetch the latest cert-manager chart available from the Helm chart repository.

      helm fetch jetstack/cert-manager --version v0.12.0

    4. Render the cert manager template with the options you would like to use to install the chart. Remember to set the image.repository option to pull the image from your private registry. This will create a cert-manager directory with the Kubernetes manifest files.

      The Helm 3 command is as follows:

      helm template cert-manager ./cert-manager-v0.12.0.tgz --output-dir . \
      --namespace cert-manager \
      --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
      --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
      --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

      The Helm 2 command is as follows:

      helm template ./cert-manager-v0.12.0.tgz --output-dir . \
      --name cert-manager --namespace cert-manager \
      --set image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-controller
      --set webhook.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-webhook
      --set cainjector.image.repository=<REGISTRY.YOURDOMAIN.COM:PORT>/quay.io/jetstack/cert-manager-cainjector

    5. Download the required CRD file for cert-manager (old and new)

      curl -L -o cert-manager/cert-manager-crd.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-0.12/deploy/manifests/00-crds.yaml
      curl -L -o cert-manager/cert-manager-crd-old.yaml https://raw.githubusercontent.com/jetstack/cert-manager/release-X.Y/deploy/manifests/00-crds.yaml

    Install cert-manager​

    1. Back up existing resources as a precaution

      kubectl get -o yaml --all-namespaces \
      issuer,clusterissuer,certificates,certificaterequests > cert-manager-backup.yaml

      Important: If you are upgrading from a version older than 0.11.0, Update the apiVersion on all your backed up resources from certmanager.k8s.io/v1alpha1 to cert-manager.io/v1alpha2. If you use any cert-manager annotations on any of your other resources, you will need to update them to reflect the new API group. For details, refer to the documentation on additional annotation changes.

    2. Delete the existing cert-manager installation

      kubectl -n cert-manager \
      delete deployment,sa,clusterrole,clusterrolebinding \
      -l 'app=cert-manager' -l 'chart=cert-manager-v0.5.2'

      Delete the CustomResourceDefinition using the link to the version vX.Y you installed

      kubectl delete -f cert-manager/cert-manager-crd-old.yaml

    3. Install the CustomResourceDefinition resources separately

      kubectl apply -f cert-manager/cert-manager-crd.yaml

      Note: If you are running Kubernetes v1.15 or below, you will need to add the --validate=false flag to your kubectl apply command above. Otherwise, you will receive a validation error relating to the x-kubernetes-preserve-unknown-fields field in cert-manager’s CustomResourceDefinition resources. This is a benign error and occurs due to the way kubectl performs resource validation.

    4. Create the namespace for cert-manager

      kubectl create namespace cert-manager

    5. Install cert-manager

      kubectl -n cert-manager apply -R -f ./cert-manager

    6. Restore back up resources

      kubectl apply -f cert-manager-backup.yaml

    Verify the Deployment​

    Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the kube-system namespace for running pods:

    kubectl get pods --namespace cert-manager

    NAME                                       READY   STATUS    RESTARTS   AGE
    cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
    cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
    cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

    Cert-Manager API change and data migration​

    Cert-manager has deprecated the use of the certificate.spec.acme.solvers field and will drop support for it completely in an upcoming release.

    Per the cert-manager documentation, a new format for configuring ACME certificate resources was introduced in v0.8. Specifically, the challenge solver configuration field was moved. Both the old format and new are supported as of v0.9, but support for the old format will be dropped in an upcoming release of cert-manager. The cert-manager documentation strongly recommends that after upgrading you update your ACME Issuer and Certificate resources to the new format.

    Details about the change and migration instructions can be found in the cert-manager v0.7 to v0.8 upgrade instructions.

    The v0.11 release marks the removal of the v1alpha1 API that was used in previous versions of cert-manager, as well as our API group changing to be cert-manager.io instead of certmanager.k8s.io.

    We have also removed support for the old configuration format that was deprecated in the v0.8 release. This means you must transition to using the new solvers style configuration format for your ACME issuers before upgrading to v0.11. For more information, see the upgrading to v0.8 guide.

    Details about the change and migration instructions can be found in the cert-manager v0.10 to v0.11 upgrade instructions.

    More info about cert-manager upgrade information.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html b/v2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html index 56ce808dc8a..37974d8f861 100644 --- a/v2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html +++ b/v2.5/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes.html @@ -5,13 +5,13 @@ Upgrading and Rolling Back Kubernetes | Rancher Manager - +
    Version: v2.5

    Upgrading and Rolling Back Kubernetes

    Following an upgrade to the latest version of Rancher, downstream Kubernetes clusters can be upgraded to use the latest supported version of Kubernetes.

    Rancher calls RKE (Rancher Kubernetes Engine) as a library when provisioning and editing RKE clusters. For more information on configuring the upgrade strategy for RKE clusters, refer to the RKE documentation.

    Tested Kubernetes Versions​

    Before a new version of Rancher is released, it's tested with the latest minor versions of Kubernetes to ensure compatibility. For details on which versions of Kubernetes were tested on each Rancher version, refer to the support maintenance terms.

    How Upgrades Work​

    RKE v1.1.0 changed the way that clusters are upgraded.

    In this section of the RKE documentation, you'll learn what happens when you edit or upgrade your RKE Kubernetes cluster.

    When upgrading the Kubernetes version of a cluster, we recommend that you:

    1. Take a snapshot.
    2. Initiate a Kubernetes upgrade.
    3. If the upgrade fails, revert the cluster to the pre-upgrade Kubernetes version. This is achieved by selecting the Restore etcd and Kubernetes version option. This will return your cluster to the pre-upgrade kubernetes version before restoring the etcd snapshot.

    The restore operation will work on a cluster that is not in a healthy or active state.

    Upgrading the Kubernetes Version​

    Prerequisites:

    1. From the Global view, find the cluster for which you want to upgrade Kubernetes. Select ⋮ > Edit.

    2. Expand Cluster Options.

    3. From the Kubernetes Version drop-down, choose the version of Kubernetes that you want to use for the cluster.

    4. Click Save.

    Result: Kubernetes begins upgrading for the cluster.

    Rolling Back

    A cluster can be restored to a backup in which the previous Kubernetes version was used. For more information, refer to the following sections:

    Configuring the Upgrade Strategy​

    As of RKE v1.1.0, additional upgrade options became available to give you more granular control over the upgrade process. These options can be used to maintain availability of your applications during a cluster upgrade if certain conditions and requirements are met.

    The upgrade strategy can be configured in the Rancher UI, or by editing the cluster.yml. More advanced options are available by editing the cluster.yml.

    Configuring the Maximum Unavailable Worker Nodes in the Rancher UI​

    From the Rancher UI, the maximum number of unavailable worker nodes can be configured. During a cluster upgrade, worker nodes will be upgraded in batches of this size.

    By default, the maximum number of unavailable worker is defined as 10 percent of all worker nodes. This number can be configured as a percentage or as an integer. When defined as a percentage, the batch size is rounded down to the nearest node, with a minimum of one node.

    To change the default number or percentage of worker nodes,

    1. Go to the cluster view in the Rancher UI.
    2. Click ⋮ > Edit.
    3. In the Advanced Options section, go to the Maxiumum Worker Nodes Unavailable field. Enter the percentage of worker nodes that can be upgraded in a batch. Optionally, select Count from the drop-down menu and enter the maximum unavailable worker nodes as an integer.
    4. Click Save.

    Result: The cluster is updated to use the new upgrade strategy.

    Enabling Draining Nodes During Upgrades from the Rancher UI​

    By default, RKE cordons each node before upgrading it. Draining is disabled during upgrades by default. If draining is enabled in the cluster configuration, RKE will both cordon and drain the node before it is upgraded.

    To enable draining each node during a cluster upgrade,

    1. Go to the cluster view in the Rancher UI.
    2. Click ⋮ > Edit.
    3. In the Advanced Options section, go to the Drain nodes field and click Yes.
    4. Choose a safe or aggressive drain option. For more information about each option, refer to this section.
    5. Optionally, configure a grace period. The grace period is the timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. Pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If this value is negative, the default value specified in the pod will be used.
    6. Optionally, configure a timeout, which is the amount of time the drain should continue to wait before giving up.
    7. Click Save.

    Result: The cluster is updated to use the new upgrade strategy.

    Note: As of Rancher v2.4.0, there is a known issue in which the Rancher UI doesn't show state of etcd and controlplane as drained, even though they are being drained.

    Maintaining Availability for Applications During Upgrades​

    Available as of RKE v1.1.0

    In this section of the RKE documentation, you'll learn the requirements to prevent downtime for your applications when upgrading the cluster.

    Configuring the Upgrade Strategy in the cluster.yml​

    More advanced upgrade strategy configuration options are available by editing the cluster.yml.

    For details, refer to Configuring the Upgrade Strategy in the RKE documentation. The section also includes an example cluster.yml for configuring the upgrade strategy.

    Troubleshooting​

    If a node doesn't come up after an upgrade, the rke up command errors out.

    No upgrade will proceed if the number of unavailable nodes exceeds the configured maximum.

    If an upgrade stops, you may need to fix an unavailable node or remove it from the cluster before the upgrade can continue.

    A failed node could be in many different states:

    • Powered off
    • Unavailable
    • User drains a node while upgrade is in process, so there are no kubelets on the node
    • The upgrade itself failed

    If the max unavailable number of nodes is reached during an upgrade, Rancher user clusters will be stuck in updating state and not move forward with upgrading any other control plane nodes. It will continue to evaluate the set of unavailable nodes in case one of the nodes becomes available. If the node cannot be fixed, you must remove the node in order to continue the upgrade.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html b/v2.5/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html index 555aa49d441..13f161aa18e 100644 --- a/v2.5/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html +++ b/v2.5/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher.html @@ -5,13 +5,13 @@ Upgrading Kubernetes without Upgrading Rancher | Rancher Manager - +
    Version: v2.5

    Upgrading Kubernetes without Upgrading Rancher

    The RKE metadata feature allows you to provision clusters with new versions of Kubernetes as soon as they are released, without upgrading Rancher. This feature is useful for taking advantage of patch versions of Kubernetes, for example, if you want to upgrade to Kubernetes v1.14.7 when your Rancher server originally supported v1.14.6.

    Note: The Kubernetes API can change between minor versions. Therefore, we don't support introducing minor Kubernetes versions, such as introducing v1.15 when Rancher currently supports v1.14. You would need to upgrade Rancher to add support for minor Kubernetes versions.

    Rancher's Kubernetes metadata contains information specific to the Kubernetes version that Rancher uses to provision RKE clusters. Rancher syncs the data periodically and creates custom resource definitions (CRDs) for system images, service options and addon templates. Consequently, when a new Kubernetes version is compatible with the Rancher server version, the Kubernetes metadata makes the new version available to Rancher for provisioning clusters. The metadata gives you an overview of the information that the Rancher Kubernetes Engine (RKE) uses for deploying various Kubernetes versions.

    This table below describes the CRDs that are affected by the periodic data sync.

    Note: Only administrators can edit metadata CRDs. It is recommended not to update existing objects unless explicitly advised.

    ResourceDescriptionRancher API URL
    System ImagesList of system images used to deploy Kubernetes through RKE.<RANCHER_SERVER_URL>/v3/rkek8ssystemimages
    Service OptionsDefault options passed to Kubernetes components like kube-api, scheduler, kubelet, kube-proxy, and kube-controller-manager<RANCHER_SERVER_URL>/v3/rkek8sserviceoptions
    Addon TemplatesYAML definitions used to deploy addon components like Canal, Calico, Flannel, Weave, Kube-dns, CoreDNS, metrics-server, nginx-ingress<RANCHER_SERVER_URL>/v3/rkeaddons

    Administrators might configure the RKE metadata settings to do the following:

    • Refresh the Kubernetes metadata, if a new patch version of Kubernetes comes out and they want Rancher to provision clusters with the latest version of Kubernetes without having to upgrade Rancher
    • Change the metadata URL that Rancher uses to sync the metadata, which is useful for air gap setups if you need to sync Rancher locally instead of with GitHub
    • Prevent Rancher from auto-syncing the metadata, which is one way to prevent new and unsupported Kubernetes versions from being available in Rancher

    Refresh Kubernetes Metadata​

    The option to refresh the Kubernetes metadata is available for administrators by default, or for any user who has the Manage Cluster Drivers global role.

    To force Rancher to refresh the Kubernetes metadata, a manual refresh action is available under Tools > Drivers > Refresh Kubernetes Metadata on the right side corner.

    You can configure Rancher to only refresh metadata when desired by setting refresh-interval-minutes to 0 (see below) and using this button to perform the metadata refresh manually when desired.

    Configuring the Metadata Synchronization​

    Only administrators can change these settings.

    The RKE metadata config controls how often Rancher syncs metadata and where it downloads data from. You can configure the metadata from the settings in the Rancher UI, or through the Rancher API at the endpoint v3/settings/rke-metadata-config.

    The way that the metadata is configured depends on the Rancher version.

    To edit the metadata config in Rancher,

    1. Go to the Global view and click the Settings tab.
    2. Go to the rke-metadata-config section. Click the ⋮ and click Edit.
    3. You can optionally fill in the following parameters:
    • refresh-interval-minutes: This is the amount of time that Rancher waits to sync the metadata. To disable the periodic refresh, set refresh-interval-minutes to 0.
    • url: This is the HTTP path that Rancher fetches data from. The path must be a direct path to a JSON file. For example, the default URL for Rancher v2.4 is https://releases.rancher.com/kontainer-driver-metadata/release-v2.4/data.json.

    If you don't have an air gap setup, you don't need to specify the URL where Rancher gets the metadata, because the default setting is to pull from Rancher's metadata Git repository.

    However, if you have an air gap setup, you will need to mirror the Kubernetes metadata repository in a location available to Rancher. Then you need to change the URL to point to the new location of the JSON file.

    Air Gap Setups​

    Rancher relies on a periodic refresh of the rke-metadata-config to download new Kubernetes version metadata if it is supported with the current version of the Rancher server. For a table of compatible Kubernetes and Rancher versions, refer to the service terms section.

    If you have an air gap setup, you might not be able to get the automatic periodic refresh of the Kubernetes metadata from Rancher's Git repository. In that case, you should disable the periodic refresh to prevent your logs from showing errors. Optionally, you can configure your metadata settings so that Rancher can sync with a local copy of the RKE metadata.

    To sync Rancher with a local mirror of the RKE metadata, an administrator would configure the rke-metadata-config settings to point to the mirror. For details, refer to Configuring the Metadata Synchronization.

    After new Kubernetes versions are loaded into the Rancher setup, additional steps would be required in order to use them for launching clusters. Rancher needs access to updated system images. While the metadata settings can only be changed by administrators, any user can download the Rancher system images and prepare a private Docker registry for them.

    1. To download the system images for the private registry, click the Rancher server version at the bottom left corner of the Rancher UI.
    2. Download the OS specific image lists for Linux or Windows.
    3. Download rancher-images.txt.
    4. Prepare the private registry using the same steps during the air gap install, but instead of using the rancher-images.txt from the releases page, use the one obtained from the previous steps.

    Result: The air gap installation of Rancher can now sync the Kubernetes metadata. If you update your private registry when new versions of Kubernetes are released, you can provision clusters with the new version without having to upgrade Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/introduction/overview.html b/v2.5/getting-started/introduction/overview.html index c625b6e95c7..593117e646f 100644 --- a/v2.5/getting-started/introduction/overview.html +++ b/v2.5/getting-started/introduction/overview.html @@ -5,13 +5,13 @@ Overview | Rancher Manager - +
    Version: v2.5

    Overview

    Rancher is a container management platform built for organizations that deploy containers in production. Rancher makes it easy to run Kubernetes everywhere, meet IT requirements, and empower DevOps teams.

    Run Kubernetes Everywhere

    Kubernetes has become the container orchestration standard. Most cloud and virtualization vendors now offer it as standard infrastructure. Rancher users have the choice of creating Kubernetes clusters with Rancher Kubernetes Engine (RKE) or cloud Kubernetes services, such as GKE, AKS, and EKS. Rancher users can also import and manage their existing Kubernetes clusters created using any Kubernetes distribution or installer.

    Meet IT requirements

    Rancher supports centralized authentication, access control, and monitoring for all Kubernetes clusters under its control. For example, you can:

    • Use your Active Directory credentials to access Kubernetes clusters hosted by cloud vendors, such as GKE.
    • Setup and enforce access control and security policies across all users, groups, projects, clusters, and clouds.
    • View the health and capacity of your Kubernetes clusters from a single-pane-of-glass.

    Empower DevOps Teams

    Rancher provides an intuitive user interface for DevOps engineers to manage their application workload. The user does not need to have in-depth knowledge of Kubernetes concepts to start using Rancher. Rancher catalog contains a set of useful DevOps tools. Rancher is certified with a wide selection of cloud native ecosystem products, including, for example, security tools, monitoring systems, container registries, and storage and networking drivers.

    The following figure illustrates the role Rancher plays in IT and DevOps organizations. Each team deploys their applications on the public or private clouds they choose. IT administrators gain visibility and enforce policies across all users, clusters, and clouds.

    Platform

    Features of the Rancher API Server

    The Rancher API server is built on top of an embedded Kubernetes API server and an etcd database. It implements the following functionalities:

    Authorization and Role-Based Access Control​

    • User management: The Rancher API server manages user identities that correspond to external authentication providers like Active Directory or GitHub, in addition to local users.
    • Authorization: The Rancher API server manages access control and security policies.

    Working with Kubernetes​

    • Provisioning Kubernetes clusters: The Rancher API server can provision Kubernetes on existing nodes, or perform Kubernetes upgrades.
    • Catalog management: Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications.
    • Managing projects: A project is a group of multiple namespaces and access control policies within a cluster. A project is a Rancher concept, not a Kubernetes concept, which allows you to manage multiple namespaces as a group and perform Kubernetes operations in them. The Rancher UI provides features for project administration and for managing applications within projects.
    • Pipelines: Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects.
    • Istio: Our integration with Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

    Working with Cloud Infrastructure​

    • Tracking nodes: The Rancher API server tracks identities of all the nodes in all clusters.
    • Setting up infrastructure: When configured to use a cloud provider, Rancher can dynamically provision new nodes and persistent storage in the cloud.

    Cluster Visibility​

    • Logging: Rancher can integrate with a variety of popular logging services and tools that exist outside of your Kubernetes clusters.
    • Monitoring: Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.
    • Alerting: To keep your clusters and applications healthy and driving your organizational productivity forward, you need to stay informed of events occurring in your clusters and projects, both planned and unplanned.

    Editing Downstream Clusters with Rancher

    The options and settings available for an existing cluster change based on the method that you used to provision it. For example, only clusters provisioned by RKE have Cluster Options available for editing.

    After a cluster is created with Rancher, a cluster administrator can manage cluster membership, enable pod security policies, and manage node pools, among other options.

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher Launched Kubernetes ClustersEKS and GKE Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓
    Authorized Cluster Endpoint✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/introduction/what-are-divio-docs.html b/v2.5/getting-started/introduction/what-are-divio-docs.html index 960eef33c2a..771c81b9fb9 100644 --- a/v2.5/getting-started/introduction/what-are-divio-docs.html +++ b/v2.5/getting-started/introduction/what-are-divio-docs.html @@ -5,13 +5,13 @@ What Are Divio Docs? | Rancher Manager - +
    Version: v2.5

    What Are Divio Docs?

    The Divio documentation system is a software documentation paradigm that is based on functionality and the premise that the best documentation is specific, concise, and purposeful. Divio traditionally consists of four main categories: tutorials, how-to guides, reference guides, and explanations.

    In our docs, we have used this guideline to craft a unique set of docs which include getting started, how-to guides (including new and advanced user guides), reference guides, explanations, an FAQ section, troubleshooting tips, and the ability to contribute to Rancher.

    Getting Started​

    To get up and running with Rancher quickly, we have included a Getting Started section.

    The goal of this section is to be able to assist users in deploying Rancher and workloads and to install or upgrade Rancher quickly and effectively.

    Please see the introduction, quick start guides, and the installation and upgrade sections for more.

    How-to Guides​

    How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

    New User Guides​

    New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

    The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

    The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

    A good example of a new user guide can be found here.

    Advanced User Guides​

    Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.

    It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

    A good example of an advanced user guide can be found here.

    Reference Guides​

    Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

    These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

    The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

    Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

    Explanations​

    Explanation docs are concerned primarily with providing theoretical knowledge for the "why" behind a task or a topic. Explanations are "understanding-oriented" in nature and will clarify a topic in order to broaden the user's knowledge. In this section, users can find additional context and background, alternatives or even opinions on topics, and often historical reasons, constraints, and insights into why a process works the way that it does.

    Explanatory docs do not instruct the user how to do something, as in tutorials and how-to guides, nor do they give detailed descriptions as references do. Explanations serve to give substance and background on both simple and complex topics.

    For our new docs, we are working to build up this section as most of our previous documentation was process-oriented rather than discussion-oriented. Currently, we feature Integrations in Rancher to discuss our integrated products.

    Integrations in Rancher​

    Over time, Rancher has accrued several products and projects that have been integrated into the Rancher UI. To assist users in learning more about these integrations, this subsection has been added under Explanations.

    Examples of some of these integrations are Fleet - GitOps at Scale and Monitoring and Alerting.

    Other Docs Categories​

    FAQ​

    Our FAQ section is designed to answer the questions our users have been most often asking about Rancher v2.x. The nature of these questions may be technical or non-technical.

    We work to continually add to and enhance this section; check back frequently for updates.

    Troubleshooting​

    The troubleshooting section is designed to help both new and existing Rancher users to troubleshoot known issues that they may encounter when using Rancher.

    We work to continually add to and enhance this section; check back frequently for updates.

    Contribute to Rancher​

    The Rancher Manager documentation is always a work-in-progress; the docs work best when being constantly examined, updated, and improved upon. To do this more effectively, we call upon the community to assist us.

    This contributing to Rancher section will instruct users on the repositories used for Rancher, how to build the repositories, and what information is needed when filing an issue or creating a pull request.

    We review all contributions frequently and will provide feedback to contributors promptly.

    Overlapping of Categories​

    You may have noticed that within the confines of each category - new user guides, advanced user guides, references - there is some overlap. This is true because the flow of information is fluid, and so often docs will include data that could logically fall under more than one category. Although there is the tendency for our docs to overlap somewhat, if we keep in mind the primary functions of each category and work to make those distinct, then the documentation will be much clearer and useful for users.

    New Structure Goals​

    Our previous Rancher documentation focused on individual features and topics; the new Divio paradigm prioritizes function and cohesion.

    Because the previous docs structure was not based on the Divio paradigm, not every doc as it is written currently will fall neatly into a user guide or a reference, for example. Some docs may include elements of several kind of documentation functions.

    As such, we have worked to move our existing documentation into the new paradigm based on each doc's function. Moving forward, we will be creating, rewriting, and reshaping our docs as needed to more closely align with the Divio structure, purpose, and its design concepts.

    Ultimately, the finished product will much more cohesively and effectively assist our users by emphasizing functionality over individual topic or feature-based docs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/aws.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/aws.html index cd16e9c28c9..f2da839a79c 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/aws.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/aws.html @@ -5,7 +5,7 @@ Rancher AWS Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Amazon AWS will incur charges.

    • Amazon AWS Account: An Amazon AWS Account is required to create resources for deploying Rancher and Kubernetes.
    • Amazon AWS Access Key: Use this link to follow a tutorial to create an Amazon AWS Access Key if you don't have one yet.
    • IAM Policy created: Defines the permissions an account attached with this policy has.
    • Install Terraform: Used to provision the server and cluster in Amazon AWS.

    Example IAM Policy​

    The AWS module just creates an EC2 KeyPair, an EC2 SecurityGroup and an EC2 instance. A simple policy would be:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "ec2:*",
                "Resource": "*"
            }
        ]
    }

    Getting Started​

    1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

    2. Go into the AWS folder containing the terraform files by executing cd quickstart/aws.

    3. Rename the terraform.tfvars.example file to terraform.tfvars.

    4. Edit terraform.tfvars and customize the following variables:

      • aws_access_key - Amazon AWS Access Key
      • aws_secret_key - Amazon AWS Secret Key
      • rancher_server_admin_password - Admin password for created Rancher server

    5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the AWS Quickstart Readme for more information. Suggestions include:

      - `aws_region` - Amazon AWS region, choose the closest instead of the default (`us-east-1`)
      - `prefix` - Prefix for all created resources
      - `instance_type` - EC2 instance size used, minimum is `t3a.medium` but `t3a.large` or `t3a.xlarge` could be used if within budget
      - `add_windows_node` - If true, an additional Windows worker node is added to the workload cluster

    6. Run terraform init.

    7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

      Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

      Outputs:

      rancher_node_ip = xx.xx.xx.xx
      rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
      workload_node_ip = yy.yy.yy.yy

    8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

    9. ssh to the Rancher server using the id_rsa key generated in quickstart/aws.

    Result​

    Two Kubernetes clusters are deployed into your AWS account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Destroying the Environment​

    1. From the quickstart/aws folder, execute terraform destroy --auto-approve.

    2. Wait for confirmation that all resources have been destroyed.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/azure.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/azure.html index 2e67e8d1cb4..e5b89a1c8c9 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/azure.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/azure.html @@ -5,7 +5,7 @@ Rancher Azure Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Microsoft Azure will incur charges.

    Getting Started​

    1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

    2. Go into the Azure folder containing the terraform files by executing cd quickstart/azure.

    3. Rename the terraform.tfvars.example file to terraform.tfvars.

    4. Edit terraform.tfvars and customize the following variables:

      • azure_subscription_id - Microsoft Azure Subscription ID
      • azure_client_id - Microsoft Azure Client ID
      • azure_client_secret - Microsoft Azure Client Secret
      • azure_tenant_id - Microsoft Azure Tenant ID
      • rancher_server_admin_password - Admin password for created Rancher server

    5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the Azure Quickstart Readme for more information. Suggestions include:

      - `azure_location` - Microsoft Azure region, choose the closest instead of the default (`East US`)
      - `prefix` - Prefix for all created resources
      - `instance_type` - Compute instance size used, minimum is `Standard_DS2_v2` but `Standard_DS2_v3` or `Standard_DS3_v2` could be used if within budget
      - `add_windows_node` - If true, an additional Windows worker node is added to the workload cluster
      - `windows_admin_password` - The admin password of the windows worker node

    6. Run terraform init.

    7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

      Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

      Outputs:

      rancher_node_ip = xx.xx.xx.xx
      rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
      workload_node_ip = yy.yy.yy.yy

    8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

    9. ssh to the Rancher Server using the id_rsa key generated in quickstart/azure.

    Result​

    Two Kubernetes clusters are deployed into your Azure account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Destroying the Environment​

    1. From the quickstart/azure folder, execute terraform destroy --auto-approve.

    2. Wait for confirmation that all resources have been destroyed.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html index 30f4a8d0b01..a4084e1dba7 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/digitalocean.html @@ -5,7 +5,7 @@ Rancher DigitalOcean Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to DigitalOcean will incur charges.

    • DigitalOcean Account: You will require an account on DigitalOcean as this is where the server and cluster will run.
    • DigitalOcean Access Key: Use this link to create a DigitalOcean Access Key if you don't have one.
    • Terraform: Used to provision the server and cluster to DigitalOcean.

    Getting Started​

    1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

    2. Go into the DigitalOcean folder containing the terraform files by executing cd quickstart/do.

    3. Rename the terraform.tfvars.example file to terraform.tfvars.

    4. Edit terraform.tfvars and customize the following variables:

      • do_token - DigitalOcean access key
      • rancher_server_admin_password - Admin password for created Rancher server

    5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the DO Quickstart Readme for more information. Suggestions include:

      - `do_region` - DigitalOcean region, choose the closest instead of the default (`nyc1`)
      - `prefix` - Prefix for all created resources
      - `droplet_size` - Droplet size used, minimum is `s-2vcpu-4gb` but `s-4vcpu-8gb` could be used if within budget

    6. Run terraform init.

    7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

      Apply complete! Resources: 15 added, 0 changed, 0 destroyed.

      Outputs:

      rancher_node_ip = xx.xx.xx.xx
      rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
      workload_node_ip = yy.yy.yy.yy

    8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

    9. ssh to the Rancher Server using the id_rsa key generated in quickstart/do.

    Result​

    Two Kubernetes clusters are deployed into your DigitalOcean account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Destroying the Environment​

    1. From the quickstart/do folder, execute terraform destroy --auto-approve.

    2. Wait for confirmation that all resources have been destroyed.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html index 625406d3ce2..6561544f2e1 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/gcp.html @@ -5,7 +5,7 @@ Rancher GCP Quick Start Guide | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to Google GCP will incur charges.

    • Google GCP Account: A Google GCP Account is required to create resources for deploying Rancher and Kubernetes.
    • Google GCP Project: Use this link to follow a tutorial to create a GCP Project if you don't have one yet.
    • Google GCP Service Account: Use this link and follow instructions to create a GCP service account and token file.
    • Terraform: Used to provision the server and cluster in Google GCP.

    Getting Started​

    1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

    2. Go into the GCP folder containing the terraform files by executing cd quickstart/gcp.

    3. Rename the terraform.tfvars.example file to terraform.tfvars.

    4. Edit terraform.tfvars and customize the following variables:

      • gcp_account_json - GCP service account file path and file name
      • rancher_server_admin_password - Admin password for created Rancher server

    5. Optional: Modify optional variables within terraform.tfvars. See the Quickstart Readme and the GCP Quickstart Readme for more information. Suggestions include:

      - `gcp_region` - Google GCP region, choose the closest instead of the default (`us-east4`)
      - `gcp_zone` - Google GCP zone, choose the closest instead of the default (`us-east4-a`)
      - `prefix` - Prefix for all created resources
      - `machine_type` - Compute instance size used, minimum is `n1-standard-1` but `n1-standard-2` or `n1-standard-4` could be used if within budget

    6. Run terraform init.

    7. To initiate the creation of the environment, run terraform apply --auto-approve. Then wait for output similar to the following:

      Apply complete! Resources: 16 added, 0 changed, 0 destroyed.

      Outputs:

      rancher_node_ip = xx.xx.xx.xx
      rancher_server_url = https://rancher.xx.xx.xx.xx.sslip.io
      workload_node_ip = yy.yy.yy.yy

    8. Paste the rancher_server_url from the output above into the browser. Log in when prompted (default username is admin, use the password set in rancher_server_admin_password).

    9. ssh to the Rancher Server using the id_rsa key generated in quickstart/gcp.

    Result​

    Two Kubernetes clusters are deployed into your GCP account, one running Rancher Server and the other ready for experimentation deployments. Please note that while this setup is a great way to explore Rancher functionality, a production setup should follow our high availability setup guidelines. SSH keys for the VMs are auto-generated and stored in the module directory.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Destroying the Environment​

    1. From the quickstart/gcp folder, execute terraform destroy --auto-approve.

    2. Wait for confirmation that all resources have been destroyed.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html index e4389c274aa..6e7097635d8 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.html @@ -5,14 +5,14 @@ Manual Quick Start | Rancher Manager - +
    Version: v2.5

    Manual Quick Start

    Howdy Partner! This tutorial walks you through:

    • Installation of Rancher 2.x
    • Creation of your first cluster
    • Deployment of an application, Nginx

    Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.


    ### 1. Provision a Linux Host

    Begin creation of a custom cluster by provisioning a Linux host. Your host can be:

    • A cloud-host virtual machine (VM)

    • An on-prem VM

    • A bare-metal server

      Note: When using a cloud-hosted virtual machine you need to allow inbound TCP communication to ports 80 and 443. Please see your cloud-host's documentation for information regarding port configuration.

      For a full list of port requirements, refer to Docker Installation.

      Provision the host according to our Requirements.

    2. Install Rancher​

    To install Rancher on your host, connect to it and then use a shell to install.

    1. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection.

    2. From your shell, enter the following command:

      sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher

    Result: Rancher is installed.

    3. Log In​

    Log in to Rancher to begin using the application. After you log in, you'll make some one-time configurations.

    1. Open a web browser and enter the IP address of your host: https://<SERVER_IP>.

      Replace <SERVER_IP> with your host IP address.

    2. When prompted, create a password for the default admin account there cowpoke!

    3. Set the Default View.

    • If I want to create or manage multiple clusters is selected, the Cluster Manager UI is used as the default view.
    • If I'm only going to use the cluster Rancher was installed on is selected, the Cluster Explorer UI is used as the default view.
    1. Set the Rancher Server URL. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.

      If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster.

    4. Create the Cluster​

    Welcome to Rancher! You are now able to create your first Kubernetes cluster.

    In this task, you can use the versatile Custom option. This option lets you add any Linux host (cloud-hosted VM, on-prem VM, or bare-metal) to be used in a cluster.

    1. If you chose I'm only going to use the cluster Rancher was installed on when setting the default view, click the Cluster Manager button in the upper-right of the UI to access the Clusters page.

    2. From the Clusters page, click Add Cluster.

    3. Choose Existing Nodes.

    4. Enter a Cluster Name.

    5. Skip Member Roles and Cluster Options. We'll tell you about them later.

    6. Click Next.

    7. From Node Role, select all the roles: etcd, Control, and Worker.

    8. Optional: Rancher auto-detects the IP addresses used for Rancher communication and cluster communication. You can override these using Public Address and Internal Address in the Node Address section.

    9. Skip the Labels stuff. It's not important for now.

    10. Copy the command displayed on screen to your clipboard.

    11. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

    12. When you finish running the command on your Linux host, click Done.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Finished​

    Congratulations! You have created your first cluster.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html index f58bbbc617d..f3208584843 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html +++ b/v2.5/getting-started/quick-start-guides/deploy-rancher-manager/vagrant.html @@ -5,13 +5,13 @@ Vagrant Quick Start | Rancher Manager - +
    Version: v2.5

    Vagrant Quick Start

    The following steps quickly deploy a Rancher Server with a single node cluster attached.

    Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

    Prerequisites​

    • Vagrant: Vagrant is required as this is used to provision the machine based on the Vagrantfile.
    • Virtualbox: The virtual machines that Vagrant provisions need to be provisioned to VirtualBox.
    • At least 4GB of free RAM.

    Note​

    • Vagrant will require plugins to create VirtualBox VMs. Install them with the following commands:

      vagrant plugin install vagrant-vboxmanage

      vagrant plugin install vagrant-vbguest

    Getting Started​

    1. Clone Rancher Quickstart to a folder using git clone https://github.com/rancher/quickstart.

    2. Go into the folder containing the Vagrantfile by executing cd quickstart/vagrant.

    3. Optional: Edit config.yaml to:

      • Change the number of nodes and the memory allocations, if required. (node.count, node.cpus, node.memory)
      • Change the password of the admin user for logging into Rancher. (admin_password)

    4. To initiate the creation of the environment run, vagrant up --provider=virtualbox.

    5. Once provisioning finishes, go to https://192.168.56.101 in the browser. The default user/password is admin/admin.

    Result: Rancher Server and your Kubernetes cluster is installed on VirtualBox.

    What's Next?​

    Use Rancher to create a deployment. For more information, see Creating Deployments.

    Destroying the Environment​

    1. From the quickstart/vagrant folder execute vagrant destroy -f.

    2. Wait for the confirmation that all resources have been destroyed.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-workloads/nodeports.html b/v2.5/getting-started/quick-start-guides/deploy-workloads/nodeports.html index 1328c2cd9cb..04a18ba71dc 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-workloads/nodeports.html +++ b/v2.5/getting-started/quick-start-guides/deploy-workloads/nodeports.html @@ -5,13 +5,13 @@ Workload with NodePort Quick Start | Rancher Manager - +
    Version: v2.5

    Workload with NodePort Quick Start

    Prerequisite​

    You have a running cluster with at least 1 node.

    1. Deploying a Workload​

    You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

    For this workload, you'll be deploying the application Rancher Hello-World.

    1. From the Clusters page, open the cluster that you just created.

    2. From the main menu of the Dashboard, select Projects/Namespaces.

    3. Open the Project: Default project.

    4. Click Resources > Workloads.

    5. Click Deploy.

      Step Result: The Deploy Workload page opens.

    6. Enter a Name for your workload.

    7. From the Docker Image field, enter rancher/hello-world. This field is case-sensitive.

    8. From Port Mapping, click Add Port.

    9. From the As a drop-down, make sure that NodePort (On every node) is selected.

      As a dropdown, NodePort (On every node selected)

    10. From the On Listening Port field, leave the Random value in place.

      On Listening Port, Random selected

    11. From the Publish the container port field, enter port 80.

      Publish the container port, 80 entered

    12. Leave the remaining options on their default setting. We'll tell you about them later.

    13. Click Launch.

    Result:

    • Your workload is deployed. This process might take a few minutes to complete.
    • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

    2. Viewing Your Application​

    From the Workloads page, click the link underneath your workload. If your deployment succeeded, your application opens.

    Attention: Cloud-Hosted Sandboxes​

    When using a cloud-hosted virtual machine, you may not have access to the port running the container. In this event, you can test Nginx in an ssh session on the local machine using Execute Shell. Use the port number after the : in the link under your workload if available, which is 31568 in this example.

    gettingstarted@rancher:~$ curl http://localhost:31568
    <!DOCTYPE html>
    <html>
      <head>
        <title>Rancher</title>
        <link rel="icon" href="img/favicon.png">
        <style>
          body {
            background-color: white;
            text-align: center;
            padding: 50px;
            font-family: "Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;
          }
          button {
              background-color: #0075a8;
              border: none;
              color: white;
              padding: 15px 32px;
              text-align: center;
              text-decoration: none;
              display: inline-block;
              font-size: 16px;
          }

          #logo {
            margin-bottom: 40px;
          }
        </style>
      </head>
      <body>
        <img id="logo" src="img/rancher-logo.svg" alt="Rancher logo" width=400 />
        <h1>Hello world!</h1>
        <h3>My hostname is hello-world-66b4b9d88b-78bhx</h3>
        <div id='Services'>
          <h3>k8s services found 2</h3>

          <b>INGRESS_D1E1A394F61C108633C4BD37AEDDE757</b> tcp://10.43.203.31:80<br />

          <b>KUBERNETES</b> tcp://10.43.0.1:443<br />

        </div>
        <br />

        <div id='rancherLinks' class="row social">
          <a class="p-a-xs" href="https://rancher.com/docs"><img src="img/favicon.png" alt="Docs" height="25" width="25"></a>
          <a class="p-a-xs" href="https://slack.rancher.io/"><img src="img/icon-slack.svg" alt="slack" height="25" width="25"></a>
          <a class="p-a-xs" href="https://github.com/rancher/rancher"><img src="img/icon-github.svg" alt="github" height="25" width="25"></a>
          <a class="p-a-xs" href="https://twitter.com/Rancher_Labs"><img src="img/icon-twitter.svg" alt="twitter" height="25" width="25"></a>
          <a class="p-a-xs" href="https://www.facebook.com/rancherlabs/"><img src="img/icon-facebook.svg" alt="facebook" height="25" width="25"></a>
          <a class="p-a-xs" href="https://www.linkedin.com/groups/6977008/profile"><img src="img/icon-linkedin.svg" height="25" alt="linkedin" width="25"></a>
        </div>
        <br />
        <button class='button' onclick='myFunction()'>Show request details</button>
        <div id="reqInfo" style='display:none'>
          <h3>Request info</h3>
          <b>Host:</b> 172.22.101.111:31411 <br />
          <b>Pod:</b> hello-world-66b4b9d88b-78bhx </b><br />

          <b>Accept:</b> [*/*]<br />

          <b>User-Agent:</b> [curl/7.47.0]<br />

        </div>
        <br />
        <script>
          function myFunction() {
              var x = document.getElementById("reqInfo");
              if (x.style.display === "none") {
                  x.style.display = "block";
              } else {
                  x.style.display = "none";
              }
          }
        </script>
      </body>
    </html>
    gettingstarted@rancher:~$

    Finished​

    Congratulations! You have successfully deployed a workload exposed via a NodePort.

    What's Next?​

    When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html b/v2.5/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html index 154c6975dd1..db532b53747 100644 --- a/v2.5/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html +++ b/v2.5/getting-started/quick-start-guides/deploy-workloads/workload-ingress.html @@ -5,13 +5,13 @@ Workload with Ingress Quick Start | Rancher Manager - +
    Version: v2.5

    Workload with Ingress Quick Start

    Prerequisite​

    You have a running cluster with at least 1 node.

    1. Deploying a Workload​

    You're ready to create your first Kubernetes workload. A workload is an object that includes pods along with other files and info needed to deploy your application.

    For this workload, you'll be deploying the application Rancher Hello-World.

    1. From the Clusters page, open the cluster that you just created.

    2. From the main menu of the Dashboard, select Projects/Namespaces.

    3. Open the Project: Default project.

    4. Click Resources > Workloads.

    5. Click Deploy.

      Step Result: The Deploy Workload page opens.

    6. Enter a Name for your workload.

    7. From the Docker Image field, enter rancher/hello-world. This field is case-sensitive.

    8. Leave the remaining options on their default setting. We'll tell you about them later.

    9. Click Launch.

    Result:

    • Your workload is deployed. This process might take a few minutes to complete.
    • When your workload completes deployment, it's assigned a state of Active. You can view this status from the project's Workloads page.

    ### 2. Expose The Application Via An Ingress

    Now that the application is up and running it needs to be exposed so that other services can connect.

    1. From the Clusters page, open the cluster that you just created.

    2. From the main menu of the Dashboard, select Projects.

    3. Open the Default project.

    4. Click Resources > Workloads > Load Balancing. Click on the Load Balancing tab.

    5. Click Add Ingress.

    6. Enter a name i.e. hello.

    7. In the Target field, drop down the list and choose the name that you set for your service.

    8. Enter 80 in the Port field.

    9. Leave everything else as default and click Save.

    Result: The application is assigned a sslip.io address and exposed. It may take a minute or two to populate.

    View Your Application​

    From the Load Balancing page, click the target link, which will look something like hello.default.xxx.xxx.xxx.xxx.sslip.io > hello-world.

    Your application will open in a separate window.

    Finished​

    Congratulations! You have successfully deployed a workload exposed via an ingress.

    What's Next?​

    When you're done using your sandbox, destroy the Rancher Server and your cluster. See one of the following:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides.html b/v2.5/how-to-guides.html index b30a77e7513..63ed423a491 100644 --- a/v2.5/how-to-guides.html +++ b/v2.5/how-to-guides.html @@ -5,13 +5,13 @@ How-to Guides | Rancher Manager - +
    Version: v2.5

    How-to Guides

    How-to guides serve to describe practical steps for users to accomplish some task. In Rancher, we break down how-to guides further into new user guides and advanced user guides.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html index 7519e506304..33039725d5a 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-active-directory.html @@ -5,13 +5,13 @@ Configuring Active Directory (AD) | Rancher Manager - +
    Version: v2.5

    Configuring Active Directory (AD)

    If your organization uses Microsoft Active Directory as central user repository, you can configure Rancher to communicate with an Active Directory server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the Active Directory, while allowing end-users to authenticate with their AD credentials when logging in to the Rancher UI.

    Rancher uses LDAP to communicate with the Active Directory server. The authentication flow for Active Directory is therefore the same as for the OpenLDAP authentication integration.

    Note:

    Before you start, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    Prerequisites​

    You'll need to create or obtain from your AD administrator a new AD user to use as service account for Rancher. This user must have sufficient permissions to perform LDAP searches and read attributes of users and groups under your AD domain.

    Usually a (non-admin) Domain User account should be used for this purpose, as by default such user has read-only privileges for most objects in the domain partition.

    Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least Read and List Content permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.

    Using TLS?

    If the certificate used by the AD server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configuration Steps​

    Open Active Directory Configuration​

    1. Log into the Rancher UI using the initial local admin account.
    2. From the Global view, navigate to Security > Authentication
    3. Select Active Directory. The Configure an AD server form will be displayed.

    Configure Active Directory Server Settings​

    In the section titled 1. Configure an Active Directory server, complete the fields with the information specific to your Active Directory server. Please refer to the following table for detailed information on the required values for each parameter.

    Note:

    If you are unsure about the correct values to enter in the user/group Search Base field, please refer to Identify Search Base and Schema using ldapsearch.

    Table 1: AD Server parameters

    ParameterDescription
    HostnameSpecify the hostname or IP address of the AD server
    PortSpecify the port at which the Active Directory server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
    TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS).
    Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the AD server unreachable.
    Service Account UsernameEnter the username of an AD account with read-only access to your domain partition (see Prerequisites). The username can be entered in NetBIOS format (e.g. "DOMAIN\serviceaccount") or UPN format (e.g. "serviceaccount@domain.com").
    Service Account PasswordThe password for the service account.
    Default Login DomainWhen you configure this field with the NetBIOS name of your AD domain, usernames entered without a domain (e.g. "jdoe") will automatically be converted to a slashed, NetBIOS logon (e.g. "LOGIN_DOMAIN\jdoe") when binding to the AD server. If your users authenticate with the UPN (e.g. "jdoe@acme.com") as username then this field must be left empty.
    User Search BaseThe Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
    Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave it empty. For example: "ou=groups,dc=acme,dc=com".

    Configure User/Group Schema​

    In the section titled 2. Customize Schema you must provide Rancher with a correct mapping of user and group attributes corresponding to the schema used in your directory.

    Rancher uses LDAP queries to search for and retrieve information about users and groups within the Active Directory. The attribute mappings configured in this section are used to construct search filters and resolve group membership. It is therefore paramount that the provided settings reflect the reality of your AD domain.

    Note:

    If you are unfamiliar with the schema used in your Active Directory domain, please refer to Identify Search Base and Schema using ldapsearch to determine the correct configuration values.

    User Schema​

    The table below details the parameters for the user schema section configuration.

    Table 2: User schema configuration parameters

    ParameterDescription
    Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Username AttributeThe user attribute whose value is suitable as a display name.
    Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. If your users authenticate with their UPN (e.g. "jdoe@acme.com") as username then this field must normally be set to userPrincipalName. Otherwise for the old, NetBIOS-style logon names (e.g. "jdoe") it's usually sAMAccountName.
    User Member AttributeThe attribute containing the groups that a user is a member of.
    Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the AD server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol. To match UPN usernames (e.g. jdoe@acme.com) you should usually set the value of this field to userPrincipalName.
    Search FilterThis filter gets applied to the list of users that is searched when Rancher attempts to add users to a site access list or tries to add members to clusters or projects. For example, a user search filter could be (|(memberOf=CN=group1,CN=Users,DC=testad,DC=rancher,DC=io)(memberOf=CN=group2,CN=Users,DC=testad,DC=rancher,DC=io)). Note: If the search filter does not use valid AD search syntax, the list of users will be empty.
    User Enabled AttributeThe attribute containing an integer value representing a bitwise enumeration of user account flags. Rancher uses this to determine if a user account is disabled. You should normally leave this set to the AD standard userAccountControl.
    Disabled Status BitmaskThis is the value of the User Enabled Attribute designating a disabled user account. You should normally leave this set to the default value of "2" as specified in the Microsoft Active Directory schema (see here).

    Group Schema​

    The table below details the parameters for the group schema configuration.

    Table 3: Group schema configuration parameters

    ParameterDescription
    Object ClassThe name of the object class used for group objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Name AttributeThe group attribute whose value is suitable for a display name.
    Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
    Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
    Search AttributeAttribute used to construct search filters when adding groups to clusters or projects. See description of user schema Search Attribute.
    Search FilterThis filter gets applied to the list of groups that is searched when Rancher attempts to add groups to a site access list or tries to add groups to clusters or projects. For example, a group search filter could be (|(cn=group1)(cn=group2)). Note: If the search filter does not use valid AD search syntax, the list of groups will be empty.
    Group DN AttributeThe name of the group attribute whose format matches the values in the user attribute describing a the user's memberships. See User Member Attribute.
    Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (i.e., you have groups that contain other groups as members. We advise avoiding nested groups when possible).

    Test Authentication​

    Once you have completed the configuration, proceed by testing the connection to the AD server using your AD admin account. If the test is successful, authentication with the configured Active Directory will be enabled implicitly with the account you test with set as admin.

    Note:

    The AD user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which AD account you use to perform this step.

    1. Enter the username and password for the AD account that should be mapped to the local principal account.
    2. Click Authenticate with Active Directory to finalise the setup.

    Result:

    • Active Directory authentication has been enabled.
    • You have been signed into Rancher as administrator using the provided AD credentials.

    Note:

    You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

    Annex: Identify Search Base and Schema using ldapsearch​

    In order to successfully configure AD authentication it is crucial that you provide the correct configuration pertaining to the hierarchy and schema of your AD server.

    The ldapsearch tool allows you to query your AD server to learn about the schema used for user and group objects.

    For the purpose of the example commands provided below we will assume:

    • The Active Directory server has a hostname of ad.acme.com
    • The server is listening for unencrypted connections on port 389
    • The Active Directory domain is acme
    • You have a valid AD account with the username jdoe and password secret

    Identify Search Base​

    First we will use ldapsearch to identify the Distinguished Name (DN) of the parent node(s) for users and groups:

    $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
    -h ad.acme.com -b "dc=acme,dc=com" -s sub "sAMAccountName=jdoe"

    This command performs an LDAP search with the search base set to the domain root (-b "dc=acme,dc=com") and a filter targeting the user account (sAMAccountNam=jdoe), returning the attributes for said user:

    Since in this case the user's DN is CN=John Doe,CN=Users,DC=acme,DC=com [5], we should configure the User Search Base with the parent node DN CN=Users,DC=acme,DC=com.

    Similarly, based on the DN of the group referenced in the memberOf attribute [4], the correct value for the Group Search Base would be the parent node of that value, i.e., OU=Groups,DC=acme,DC=com.

    Identify User Schema​

    The output of the above ldapsearch query also allows to determine the correct values to use in the user schema configuration:

    • Object Class: person [1]
    • Username Attribute: name [2]
    • Login Attribute: sAMAccountName [3]
    • User Member Attribute: memberOf [4]

    Note:

    If the AD users in our organization were to authenticate with their UPN (e.g. jdoe@acme.com) instead of the short logon name, then we would have to set the Login Attribute to userPrincipalName instead.

    We'll also set the Search Attribute parameter to sAMAccountName|name. That way users can be added to clusters/projects in the Rancher UI either by entering their username or full name.

    Identify Group Schema​

    Next, we'll query one of the groups associated with this user, in this case CN=examplegroup,OU=Groups,DC=acme,DC=com:

    $ ldapsearch -x -D "acme\jdoe" -w "secret" -p 389 \
    -h ad.acme.com -b "ou=groups,dc=acme,dc=com" \
    -s sub "CN=examplegroup"

    This command will inform us on the attributes used for group objects:

    Again, this allows us to determine the correct values to enter in the group schema configuration:

    • Object Class: group [1]
    • Name Attribute: name [2]
    • Group Member Mapping Attribute: member [3]
    • Search Attribute: sAMAccountName [4]

    Looking at the value of the member attribute, we can see that it contains the DN of the referenced user. This corresponds to the distinguishedName attribute in our user object. Accordingly will have to set the value of the Group Member User Attribute parameter to this attribute.

    In the same way, we can observe that the value in the memberOf attribute in the user object corresponds to the distinguishedName [5] of the group. We therefore need to set the value for the Group DN Attribute parameter to this attribute.

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the Active Directory server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html index b734ced0a47..76fc7caef8b 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-azure-ad.html @@ -5,7 +5,7 @@ Configuring Azure AD | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Configuring Azure AD

    Microsoft Graph API​

    Microsoft Graph API is now the flow through which you will set up Azure AD. The below sections will assist new users in configuring Azure AD with a new instance as well as assist existing Azure app owners in migrating to the new flow.

    New User Setup​

    If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.

    Prerequisite: Have an instance of Azure AD configured.

    Notes:

    • Azure AD integration only supports Service Provider initiated logins.
    • Most of this procedure takes place from the Microsoft Azure Portal.

    Azure Active Directory Configuration Outline​

    Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.

    Tip: Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.

    1. Register Rancher with Azure​

    Before enabling Azure AD within Rancher, you must register Rancher with Azure.

    1. Log in to Microsoft Azure as an administrative user. Configuration in future steps requires administrative access rights.

    2. Use search to open the App registrations service.

      Open App Registrations

    3. Click New registrations and complete the Create form.

      New App Registration

      3.1. Enter a Name (something like Rancher).

      3.2. From Supported account types, select "Accounts in this organizational directory only (AzureADTest only - Single tenant)" This corresponds to the legacy app registration options.

      Important: In the updated Azure portal, Redirect URIs are synonymous with Reply URLs. In order to use Azure AD with Rancher, you must whitelist Rancher with Azure (previously done through Reply URLs). Therefore, you must ensure to fill in the Redirect URI with your Rancher server URL, to include the verification path as listed below.

      3.3. In the Redirect URI section, make sure Web is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: <MY_RANCHER_URL>/verify-auth-azure.

      Tip: You can find your personalized Azure Redirect URI (reply URL) in Rancher on the Azure AD Authentication page (Global View > Authentication > Web).

      3.4. Click Register.

    Important: It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.

    2. Create a new client secret​

    From the Azure portal, create a client secret. Rancher will use this key to authenticate with Azure AD.

    1. Use search to open App registrations services. Then open the entry for Rancher that you created in the last procedure.

      Open Rancher Registration

    2. From the navigation pane on left, click Certificates and Secrets.

    3. Click New client secret. Create new client secret

      • 3.1. Enter a Description (something like Rancher).
      • 3.2. Select duration for the key from the options under Expires. This drop-down sets the expiration date for the key. Shorter durations are more secure, but require you to create a new key after expiration.
      • 3.3. Click Add (you don't need to enter a value—it will automatically populate after you save).

    4. Copy the key value and save it to an empty text file.

      You'll enter this key into the Rancher UI later as your Application Secret.

      You won't be able to access the key value again within the Azure UI.

    3. Set Required Permissions for Rancher​

    Next, set API permissions for Rancher within Azure.

    caution

    Ensure that you set the permissions of type Application and NOT Delegated. Otherwise, you may not be able to login to Azure AD. This issue will persist even after you disable/re-enable Azure AD and will require an hour wait, or manual deletion of a cache value to resolve.

    1. From the navigation pane on left, select API permissions.

      Open Required Permissions

    2. Click Add a permission.

    3. From the Microsoft Graph, select the following Application Permissions:

      • Group.Read.All
      • User.Read.All

    1. Return to API permissions in the left nav bar. From there, click Grant admin consent. Then click Yes.

      Note: You must be signed in as an Azure administrator to successfully save your permission settings.

    4. Copy Azure Application Data​

    As your final step in Azure, copy the data that you'll use to configure Rancher for Azure AD authentication and paste it into an empty text file.

    1. Obtain your Rancher Tenant ID.

      1. Use search to open App registrations.

      Open App Registrations

      1. Find the entry you created for Rancher.

      2. Copy the Directory ID and paste it into your text file.

      Tenant ID

      • You'll paste this value into Rancher as your Tenant ID.

    2. Obtain your Rancher Application (Client) ID.

      1. Use search to open App registrations (if not already there).

      2. In Overview, find the entry you created for Rancher.

      3. Copy the Application (Client) ID and paste it to your text file.

      Application ID

    3. Your endpoint options will typically be Standard and China. With the Standard option, perform the steps below and Rancher will take care of the rest.

      • Enter the Tenant ID, Application ID, and Application Secret
      • Click Enable

    Standard Endpoint Options

    For Custom Endpoints:

    Warning: Custom Endpoints are not supported nor fully tested by Rancher.

    You will need to also manually enter the Graph, Token, and Auth Endpoints.

    • From App registrations, click Endpoints:

    Click Endpoints

    • Copy the following endpoints to your clipboard and paste them into your text file (these values will be your Rancher endpoint values). Make sure to copy the v1 version of the endpoints.

      • Microsoft Graph API endpoint (Graph Endpoint)
      • OAuth 2.0 token endpoint (v1) (Token Endpoint)
      • OAuth 2.0 authorization endpoint (v1) (Auth Endpoint)

    5. Configure Azure AD in Rancher​

    From the Rancher UI, enter information about your AD instance hosted in Azure to complete configuration.

    Enter the values that you copied to your text file.

    1. Log into Rancher.

    2. In the top left corner, click ☰ > Users & Authentication.

    3. In the left navigation menu, click Auth Provider.

    4. Click AzureAD.

    5. Complete the Configure Azure AD Account form using the information you copied while completing Copy Azure Application Data.

      The following table maps the values you copied in the Azure portal to the fields in Rancher.

      Rancher FieldAzure Value
      Tenant IDDirectory ID
      Application IDApplication ID
      Application SecretKey Value
      Endpointhttps://login.microsoftonline.com/

    For Custom Endpoints:


    The following table maps the custom config values you copied in the Azure portal to the fields in Rancher:
    Rancher FieldAzure Value
    Graph EndpointMicrosoft Graph API Endpoint
    Token EndpointOAuth 2.0 Token Endpoint
    Auth EndpointOAuth 2.0 Authorization Endpoint

    **Important:** When entering the Graph Endpoint in a custom config, remove the tenant ID from the URL, like below:
    https://graph.microsoft.com/abb5adde-bee8-4821-8b03-e63efdc7701c
    1. Click Enable.

    Result: Azure Active Directory authentication is configured.

    Migrating from Azure AD Graph API to Microsoft Graph API​

    Since Azure AD Graph API was deprecated in June 2022 and will be retired at the end of 2022, users should update their Azure AD App to use the new Microsoft Graph API in Rancher.

    Updating Endpoints in the Rancher UI​

    Important: Admins should create a [backup]../../../..//new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.md) right before they commit to the endpoint migration in Step 4 below.

    1. Update the permissions of your Azure AD app registration as described here. This is critical.

    2. Log into Rancher.

    3. In the Rancher UI homepage, make note of the banner at the top of screen that advises users to update their Azure AD authentication. Click on the link provided to do so.

      Rancher UI Banner

    4. To complete the move to the new Microsoft Graph API, click Update Endpoint, then click Save.

      Note: Ensure that your Azure app has a new set of permissions before starting the update.

      Update Endpoint

    5. When you receive the pop-up warning message, click Update.

      Azure Update Pop-up

    6. Refer to the tables below for the full list of endpoint changes that Rancher performs. Admins do not need to do this manually.

    Air-Gapped Environments​

    In air-gapped environments, admins should ensure that their endpoints are whitelisted since the Graph Endpoint URL is changing.

    Rolling Back the Migration​

    If you need to roll back your migration, please note the following:

    1. Admins are encouraged to use the proper restore process if they want to go back. Please see backup docs, restore docs, and examples for reference.

    2. Azure app owners who want to rotate the Application Secret will need to also rotate it in Rancher as Rancher does not automatically update the Application Secret when it is changed in Azure. In Rancher, note that it is stored in a Kubernetes secret called azureadconfig-applicationsecret which is in the cattle-global-data namespace.

    3. Caution: If admins upgrade to Rancher v2.5.16 with an existing Azure AD setup and choose to disable the auth provider, they won't be able to restore the previous setup and also will not be able to set up Azure AD anew using the old flow. Admins will then need to register again with the new auth flow. Rancher now uses the new Graph API and, therefore, users need set up the proper permissions in the Azure portal.

    Global:​

    Rancher FieldDeprecated Endpoints
    Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/authorize
    Endpointhttps://login.microsoftonline.com/
    Graph Endpointhttps://graph.windows.net/
    Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/token
    Rancher FieldNew Endpoints
    Auth Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
    Endpointhttps://login.microsoftonline.com/
    Graph Endpointhttps://graph.microsoft.com
    Token Endpointhttps://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token

    China:​

    Rancher FieldDeprecated Endpoints
    Auth Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/authorize
    Endpointhttps://login.chinacloudapi.cn/
    Graph Endpointhttps://graph.chinacloudapi.cn/
    Token Endpointhttps://login.chinacloudapi.cn/{tenantID}/oauth2/token
    Rancher FieldNew Endpoints
    Auth Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/authorize
    Endpointhttps://login.partner.microsoftonline.cn/
    Graph Endpointhttps://microsoftgraph.chinacloudapi.cn
    Token Endpointhttps://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html index 8495e2366df..33ed89b371e 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-freeipa.html @@ -5,14 +5,14 @@ Configuring FreeIPA | Rancher Manager - +
    Version: v2.5

    Configuring FreeIPA

    If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.

    Prerequisites:

    1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

    2. From the Global view, select Security > Authentication from the main menu.

    3. Select FreeIPA.

    4. Complete the Configure an FreeIPA server form.

      You may need to log in to your domain controller to find the information requested in the form.

      Using TLS? If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.



      **User Search Base vs. Group Search Base**

      Search base allows Rancher to search for users and groups that are in your FreeIPA. These fields are only for search bases and not for search filters.

      • If your users and groups are in the same search base, complete only the User Search Base.
      • If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.

    5. If your FreeIPA deviates from the standard AD schema, complete the Customize Schema form to match it. Otherwise, skip this step.

      Search Attribute The Search Attribute field defaults with three specific values: uid|sn|givenName. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.

      The default field value uid|sn|givenName, but you can configure this field to a subset of these fields. The pipe (|) between the fields separates these fields.

      • uid: User ID
      • sn: Last Name
      • givenName: First Name

      With this search attribute, Rancher creates search filters for users and groups, but you cannot add your own search filters in this field.

    6. Enter your FreeIPA username and password in Authenticate with FreeIPA to confirm that Rancher is configured to use FreeIPA authentication.

    Result:

    • FreeIPA authentication is configured.
    • You are signed into Rancher with your FreeIPA account (i.e., the external principal).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html index f96b385980a..20d3af57877 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-github.html @@ -5,13 +5,13 @@ Configuring GitHub | Rancher Manager - +
    Version: v2.5

    Configuring GitHub

    In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.

    Prerequisites: Read External Authentication Configuration and Principal Users.

    1. Sign into Rancher using a local user assigned the administrator role (i.e., the local principal).

    2. From the Global view, select Security > Authentication from the main menu.

    3. Select GitHub.

    4. Follow the directions displayed to Setup a GitHub Application. Rancher redirects you to GitHub to complete registration.

      What's an Authorization Callback URL?

      The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).

      When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.

    5. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.

      Where do I find the Client ID and Client Secret?

      From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.

    6. Click Authenticate with GitHub.

    7. Use the Site Access options to configure the scope of user authorization.

      • Allow any valid Users

        Any GitHub user can access Rancher. We generally discourage use of this setting!

      • Allow members of Clusters, Projects, plus Authorized Users and Organizations

        Any GitHub user or group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any GitHub user or group you add to the Authorized Users and Organizations list may log in to Rancher.

      • Restrict access to only Authorized Users and Organizations

        Only GitHub users or groups added to the Authorized Users and Organizations can log in to Rancher.


    8. Click Save.

    Result:

    • GitHub authentication is configured.
    • You are signed into Rancher with your GitHub account (i.e., the external principal).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html index 7efe21315a7..4a358dbe3fa 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-google-oauth.html @@ -5,7 +5,7 @@ Configuring Google OAuth | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Configuring Google OAuth

    If your organization uses G Suite for user authentication, you can configure Rancher to allow your users to log in using their G Suite credentials.

    Only admins of the G Suite domain have access to the Admin SDK. Therefore, only G Suite admins can configure Google OAuth for Rancher.

    Within Rancher, only administrators or users with the Manage Authentication global role can configure authentication.

    Prerequisites

    • You must have a G Suite admin account configured.
    • G Suite requires a top private domain FQDN as an authorized domain. One way to get an FQDN is by creating an A-record in Route53 for your Rancher server. You do not need to update your Rancher Server URL setting with that record, because there could be clusters using that URL.
    • You must have the Admin SDK API enabled for your G Suite domain. You can enable it using the steps on this page.

    After the Admin SDK API is enabled, your G Suite domain's API screen should look like this: Enable Admin APIs

    Setting up G Suite for OAuth with Rancher

    Before you can set up Google OAuth in Rancher, you need to log in to your G Suite account and do the following:

    1. Add Rancher as an authorized domain in G Suite
    2. Generate OAuth2 credentials for the Rancher server
    3. Create service account credentials for the Rancher server
    4. Register the service account key as an OAuth Client

    1. Adding Rancher as an Authorized Domain​

    1. Click here to go to credentials page of your Google domain.
    2. Select your project and click OAuth consent screen.OAuth Consent Screen
    3. Go to Authorized Domains and enter the top private domain of your Rancher server URL in the list. The top private domain is the rightmost superdomain. So for example, www.foo.co.uk a top private domain of foo.co.uk. For more information on top-level domains, refer to this article.
    4. Go to Scopes for Google APIs and make sure email, profile and openid are enabled.

    Result: Rancher has been added as an authorized domain for the Admin SDK API.

    2. Creating OAuth2 Credentials for the Rancher Server​

    1. Go to the Google API console, select your project, and go to the credentials page.Credentials
    2. On the Create Credentials dropdown, select OAuth client ID.
    3. Click Web application.
    4. Provide a name.
    5. Fill out the Authorized JavaScript origins and Authorized redirect URIs. Note: The Rancher UI page for setting up Google OAuth (available from the Global view under Security > Authentication > Google) provides you the exact links to enter for this step.
    • Under Authorized JavaScript origins, enter your Rancher server URL.
    • Under Authorized redirect URIs, enter your Rancher server URL appended with the path verify-auth. For example, if your URI is https://rancherServer, you will enter https://rancherServer/verify-auth.
    1. Click on Create.
    2. After the credential is created, you will see a screen with a list of your credentials. Choose the credential you just created, and in that row on rightmost side, click Download JSON. Save the file so that you can provide these credentials to Rancher.

    Result: Your OAuth credentials have been successfully created.

    3. Creating Service Account Credentials​

    Since the Google Admin SDK is available only to admins, regular users cannot use it to retrieve profiles of other users or their groups. Regular users cannot even retrieve their own groups.

    Since Rancher provides group-based membership access, we require the users to be able to get their own groups, and look up other users and groups when needed.

    As a workaround to get this capability, G Suite recommends creating a service account and delegating authority of your G Suite domain to that service account.

    This section describes how to:

    • Create a service account
    • Create a key for the service account and download the credentials as JSON
    1. Click here and select your project for which you generated OAuth credentials.
    2. Click on Create Service Account.
    3. Enter a name and click Create.Service account creation Step 1
    4. Don't provide any roles on the Service account permissions page and click ContinueService account creation Step 2
    5. Click on Create Key and select the JSON option. Download the JSON file and save it so that you can provide it as the service account credentials to Rancher. Service account creation Step 3

    Result: Your service account is created.

    4. Register the Service Account Key as an OAuth Client​

    You will need to grant some permissions to the service account you created in the last step. Rancher requires you to grant only read-only permissions for users and groups.

    Using the Unique ID of the service account key, register it as an Oauth Client using the following steps:

    1. Get the Unique ID of the key you just created. If it's not displayed in the list of keys right next to the one you created, you will have to enable it. To enable it, click Unique ID and click OK. This will add a Unique ID column to the list of service account keys. Save the one listed for the service account you created. NOTE: This is a numeric key, not to be confused with the alphanumeric field Key ID.

      Service account Unique ID

    2. Go to the Manage OAuth Client Access page.

    3. Add the Unique ID obtained in the previous step in the Client Name field.

    4. In the One or More API Scopes field, add the following scopes:

      openid,profile,email,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly

    5. Click Authorize.

    Result: The service account is registered as an OAuth client in your G Suite account.

    Configuring Google OAuth in Rancher

    1. Sign into Rancher using a local user assigned the administrator role. This user is also called the local principal.
    2. From the Global view, click Security > Authentication from the main menu.
    3. Click Google. The instructions in the UI cover the steps to set up authentication with Google OAuth.
      1. Admin Email: Provide the email of an administrator account from your GSuite setup. In order to perform user and group lookups, google apis require an administrator's email in conjunction with the service account key.
      2. Domain: Provide the domain on which you have configured GSuite. Provide the exact domain and not any aliases.
      3. Nested Group Membership: Check this box to enable nested group memberships. Rancher admins can disable this at any time after configuring auth.
      • Step One is about adding Rancher as an authorized domain, which we already covered in this section.
      • For Step Two, provide the OAuth credentials JSON that you downloaded after completing this section. You can upload the file or paste the contents into the OAuth Credentials field.
      • For Step Three, provide the service account credentials JSON that downloaded at the end of this section. The credentials will only work if you successfully registered the service account key as an OAuth client in your G Suite account.
    4. Click Authenticate with Google.
    5. Click Save.

    Result: Google authentication is successfully configured.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html index 808f368800c..6c077871899 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-keycloak.html @@ -5,7 +5,7 @@ Configuring Keycloak (SAML) | Rancher Manager - + @@ -15,7 +15,7 @@

    Getting the IDP Metadata​

    To get the IDP metadata, export a metadata.xml file from your Keycloak client. From the Installation tab, choose the SAML Metadata IDPSSODescriptor format option and download your file.

    Configuring Keycloak in Rancher​

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Keycloak.

    3. Complete the Configure Keycloak Account form. For help with filling the form, see the configuration reference.

    4. After you complete the Configure Keycloak Account form, click Authenticate with Keycloak, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

      Note: You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    Configuration Reference​

    FieldDescription
    Display Name FieldThe attribute that contains the display name of users.

    Example: givenName
    User Name FieldThe attribute that contains the user name/given name.

    Example: email
    UID FieldAn attribute that is unique to every user.

    Example: email
    Groups FieldMake entries for managing group memberships.

    Example: member
    Entity ID FieldThe ID that needs to be configured as a client ID in the Keycloak client.

    Default: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata
    Rancher API HostThe URL for your Rancher Server.
    Private Key / CertificateA key/certificate pair to create a secure shell between Rancher and your IdP.
    IDP-metadataThe metadata.xml file that you exported from your IdP server.

    Tip: You can generate a key/certificate pair using an openssl command. For example:

       openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the Keycloak server, first double-check the configuration option of your SAML client. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    You are not redirected to Keycloak​

    When you click on Authenticate with Keycloak, you are not redirected to your IdP.

    • Verify your Keycloak client configuration.
    • Make sure Force Post Binding set to OFF.

    Forbidden message displayed after IdP login​

    You are correctly redirected to your IdP login page and you are able to enter your credentials, however you get a Forbidden message afterwards.

    • Check the Rancher debug log.
    • If the log displays ERROR: either the Response or Assertion must be signed, make sure either Sign Documents or Sign assertions is set to ON in your Keycloak client.

    HTTP 502 when trying to access /v1-saml/keycloak/saml/metadata​

    This is usually due to the metadata not being created until a SAML provider is configured. Try configuring and saving keycloak as your SAML provider and then accessing the metadata.

    Keycloak Error: "We're sorry, failed to process response"​

    • Check your Keycloak log.
    • If the log displays failed: org.keycloak.common.VerificationException: Client does not have a public key, set Encrypt Assertions to OFF in your Keycloak client.

    Keycloak Error: "We're sorry, invalid requester"​

    • Check your Keycloak log.
    • If the log displays request validation failed: org.keycloak.common.VerificationException: SigAlg was null, set Client Signature Required to OFF in your Keycloak client.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html index cfc2e4b67a2..3c7c6d01601 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-okta-saml.html @@ -5,13 +5,13 @@ Configuring Okta (SAML) | Rancher Manager - +
    Version: v2.5

    Configuring Okta (SAML)

    If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

    Note: Okta integration only supports Service Provider initiated logins.

    Prerequisites​

    In Okta, create a SAML Application with the settings below. See the Okta documentation for help.

    SettingValue
    Single Sign on URLhttps://yourRancherHostURL/v1-saml/okta/saml/acs
    Audience URI (SP Entity ID)https://yourRancherHostURL/v1-saml/okta/saml/metadata

    Configuring Okta in Rancher​

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Okta.

    3. Complete the Configure Okta Account form. The examples below describe how you can map Okta attributes from attribute statements to fields within Rancher.

      FieldDescription
      Display Name FieldThe attribute name from an attribute statement that contains the display name of users.
      User Name FieldThe attribute name from an attribute statement that contains the user name/given name.
      UID FieldThe attribute name from an attribute statement that is unique to every user.
      Groups FieldThe attribute name in a group attribute statement that exposes your groups.
      Rancher API HostThe URL for your Rancher Server.
      Private Key / CertificateA key/certificate pair used for Assertion Encryption.
      Metadata XMLThe Identity Provider metadata file that you find in the application Sign On section.

      Tip: You can generate a key/certificate pair using an openssl command. For example:

         openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.crt

    1. After you complete the Configure Okta Account form, click Authenticate with Okta, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.

      Note: If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.

    Result: Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html index 1765ff6fabc..a2084c8d616 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/configure-pingidentity.html @@ -5,7 +5,7 @@ Configuring PingIdentity (SAML) | Rancher Manager - + @@ -14,7 +14,7 @@ Metadata URL: https://<rancher-server>/v1-saml/ping/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/ping/saml/acs Note that these URLs will not return valid data until the authentication configuration is saved in Rancher.
  • Export a metadata.xml file from your IdP Server. For more information, see the PingIdentity documentation.

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select PingIdentity.

    3. Complete the Configure Ping Account form. Ping IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Entity ID Field (optional): The published, protocol-dependent, unique identifier of your partner. This ID defines your organization as the entity operating the server for SAML 2.0 transactions. This ID may have been obtained out-of-band or via a SAML metadata file.

      6. Rancher API Host: Enter the URL for your Rancher Server.

      7. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      8. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Ping Account form, click Authenticate with Ping, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Ping IdP to validate your Rancher PingIdentity configuration.

      Note: You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html index 28374152d71..99f1138d2db 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users.html @@ -5,13 +5,13 @@ Local Authentication | Rancher Manager - +
    Version: v2.5

    Local Authentication

    Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Rancher. By default, the admin user that logs in to Rancher for the first time is a local user.

    Adding Local Users​

    Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.

    1. From the Global view, select Users from the navigation bar.

    2. Click Add User. Then complete the Add User form. Click Create when you're done.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html index 1648d1e16e5..54dae23aa39 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/manage-users-and-groups.html @@ -5,13 +5,13 @@ Users and Groups | Rancher Manager - +
    Version: v2.5

    Users and Groups

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When you configure an external authentication provider, users from that provider will be able to log in to your Rancher server. When a user logs in, the authentication provider will supply your Rancher server with a list of groups to which the user belongs.

    Access to clusters, projects, multi-cluster apps, and global DNS providers and entries can be controlled by adding either individual users or groups to these resources. When you add a group to a resource, all users who are members of that group in the authentication provider, will be able to access the resource with the permissions that you've specified for the group. For more information on roles and permissions, see Role Based Access Control.

    Managing Members​

    When adding a user or group to a resource, you can search for users or groups by beginning to type their name. The Rancher server will query the authentication provider to find users and groups that match what you've entered. Searching is limited to the authentication provider that you are currently logged in with. For example, if you've enabled GitHub authentication but are logged in using a local user account, you will not be able to search for GitHub users or groups.

    All users, whether they are local users or from an authentication provider, can be viewed and managed. From the Global view, click on Users.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    User Information​

    Rancher maintains information about each user that logs in through an authentication provider. This information includes whether the user is allowed to access your Rancher server and the list of groups that the user belongs to. Rancher keeps this user information so that the CLI, API, and kubectl can accurately reflect the access that the user has based on their group membership in the authentication provider.

    Whenever a user logs in to the UI using an authentication provider, Rancher automatically updates this user information.

    Automatically Refreshing User Information​

    Rancher will periodically refresh the user information even before a user logs in through the UI. You can control how often Rancher performs this refresh. From the Global view, click on Settings. Two settings control this behavior:

    • auth-user-info-max-age-seconds

      This setting controls how old a user's information can be before Rancher refreshes it. If a user makes an API call (either directly or by using the Rancher CLI or kubectl) and the time since the user's last refresh is greater than this setting, then Rancher will trigger a refresh. This setting defaults to 3600 seconds, i.e. 1 hour.

    • auth-user-info-resync-cron

      This setting controls a recurring schedule for resyncing authentication provider information for all users. Regardless of whether a user has logged in or used the API recently, this will cause the user to be refreshed at the specified interval. This setting defaults to 0 0 * * *, i.e. once a day at midnight. See the Cron documentation for more information on valid values for this setting.

    Note: Since SAML does not support user lookup, SAML-based authentication providers do not support periodically refreshing user information. User information will only be refreshed when the user logs into the Rancher UI.

    Manually Refreshing User Information​

    If you are not sure the last time Rancher performed an automatic refresh of user information, you can perform a manual refresh of all users.

    1. From the Global view, click on Users in the navigation bar.

    2. Click on Refresh Group Memberships.

    Results: Rancher refreshes the user information for all users. Requesting this refresh will update which users can access Rancher as well as all the groups that each user belongs to.

    Note: Since SAML does not support user lookup, SAML-based authentication providers do not support the ability to manually refresh user information. User information will only be refreshed when the user logs into the Rancher UI.

    Session Length​

    The default length (TTL) of each user session is adjustable. The default session length is 16 hours.

    1. From the Global view, click on Settings.
    2. In the Settings page, find auth-user-session-ttl-minutes and click Edit.
    3. Enter the amount of time in minutes a session length should last and click Save.

    Result: Users are automatically logged out of Rancher after the set number of minutes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html index c02544caef7..766653530f8 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-ms-adfs-for-rancher.html @@ -5,14 +5,14 @@ 1. Configuring Microsoft AD FS for Rancher | Rancher Manager - +
    Version: v2.5

    1. Configuring Microsoft AD FS for Rancher

    Before configuring Rancher to support AD FS users, you must add Rancher as a relying party trust in AD FS.

    1. Log into your AD server as an administrative user.

    2. Open the AD FS Management console. Select Add Relying Party Trust... from the Actions menu and click Start.

    3. Select Enter data about the relying party manually as the option for obtaining data about the relying party.

    4. Enter your desired Display name for your Relying Party Trust. For example, Rancher.

    5. Select AD FS profile as the configuration profile for your relying party trust.

    6. Leave the optional token encryption certificate empty, as Rancher AD FS will not be using one.

    7. Select Enable support for the SAML 2.0 WebSSO protocol and enter https://<rancher-server>/v1-saml/adfs/saml/acs for the service URL.

    8. Add https://<rancher-server>/v1-saml/adfs/saml/metadata as the Relying party trust identifier.

    9. This tutorial will not cover multi-factor authentication; please refer to the Microsoft documentation if you would like to configure multi-factor authentication.

    10. From Choose Issuance Authorization RUles, you may select either of the options available according to use case. However, for the purposes of this guide, select Permit all users to access this relying party.

    11. After reviewing your settings, select Next to add the relying party trust.

    1. Select Open the Edit Claim Rules... and click Close.

    2. On the Issuance Transform Rules tab, click Add Rule....

    3. Select Send LDAP Attributes as Claims as the Claim rule template.

    4. Set the Claim rule name to your desired name (for example, Rancher Attributes) and select Active Directory as the Attribute store. Create the following mapping to reflect the table below:

      LDAP AttributeOutgoing Claim Type
      Given-NameGiven Name
      User-Principal-NameUPN
      Token-Groups - Qualified by Long Domain NameGroup
      SAM-Account-NameName

      ![](/img/adfs/adfs-add-tcr-2.png)

    5. Download the federationmetadata.xml from your AD server at:

    https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    Result: You've added Rancher as a relying trust party. Now you can configure Rancher to leverage AD.

    Next: Configuring Rancher for Microsoft AD FS​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html index ddfb6cd3886..80124823761 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-microsoft-ad-federation-service-saml/configure-rancher-for-ms-adfs.html @@ -5,13 +5,13 @@ 2. Configuring Rancher for Microsoft AD FS | Rancher Manager - +
    Version: v2.5

    2. Configuring Rancher for Microsoft AD FS

    After you complete Configuring Microsoft AD FS for Rancher, enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.

    Important Notes For Configuring Your AD FS Server:

    • The SAML 2.0 WebSSO Protocol Service URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs
    • The Relying Party Trust identifier URL is: https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata
    • You must export the federationmetadata.xml file from your AD FS server. This can be found at: https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Microsoft Active Directory Federation Services.

    3. Complete the Configure AD FS Account form. Microsoft AD FS lets you specify an existing Active Directory (AD) server. The configuration section below describe how you can map AD attributes to fields within Rancher.

    1. After you complete the Configure AD FS Account form, click Authenticate with AD FS, which is at the bottom of the page.

      Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.

      Note: You may have to disable your popup blocker to see the AD FS login page.

    Result: Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.

    Configuration

    FieldDescription
    Display Name FieldThe AD attribute that contains the display name of users.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    User Name FieldThe AD attribute that contains the user name/given name.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    UID FieldAn AD attribute that is unique to every user.

    Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
    Groups FieldMake entries for managing group memberships.

    Example: http://schemas.xmlsoap.org/claims/Group
    Rancher API HostThe URL for your Rancher Server.
    Private Key / CertificateThis is a key-certificate pair to create a secure shell between Rancher and your AD FS. Ensure you set the Common Name (CN) to your Rancher Server URL.

    Certificate creation command
    Metadata XMLThe federationmetadata.xml file exported from your AD FS server.

    You can find this file at https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml.

    Tip: You can generate a certificate using an openssl command. For example:

    openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html index 5180f314240..f8a8b30a260 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/configure-shibboleth-saml/about-group-permissions.html @@ -5,13 +5,13 @@ Group Permissions with Shibboleth and OpenLDAP | Rancher Manager - +
    Version: v2.5

    Group Permissions with Shibboleth and OpenLDAP

    This page provides background information and context for Rancher users who intend to set up the Shibboleth authentication provider in Rancher.

    Because Shibboleth is a SAML provider, it does not support searching for groups. While a Shibboleth integration can validate user credentials, it can't be used to assign permissions to groups in Rancher without additional configuration.

    One solution to this problem is to configure an OpenLDAP identity provider. With an OpenLDAP back end for Shibboleth, you will be able to search for groups in Rancher and assign them to resources such as clusters, projects, or namespaces from the Rancher UI.

    Terminology​

    • Shibboleth is a single sign-on log-in system for computer networks and the Internet. It allows people to sign in using just one identity to various systems. It validates user credentials, but does not, on its own, handle group memberships.
    • SAML: Security Assertion Markup Language, an open standard for exchanging authentication and authorization data between an identity provider and a service provider.
    • OpenLDAP: a free, open-source implementation of the Lightweight Directory Access Protocol (LDAP). It is used to manage an organization’s computers and users. OpenLDAP is useful for Rancher users because it supports groups. In Rancher, it is possible to assign permissions to groups so that they can access resources such as clusters, projects, or namespaces, as long as the groups already exist in the identity provider.
    • IdP or IDP: An identity provider. OpenLDAP is an example of an identity provider.

    Adding OpenLDAP Group Permissions to Rancher Resources​

    The diagram below illustrates how members of an OpenLDAP group can access resources in Rancher that the group has permissions for.

    For example, a cluster owner could add an OpenLDAP group to a cluster so that they have permissions view most cluster level resources and create new projects. Then the OpenLDAP group members will have access to the cluster as soon as they log in to Rancher.

    In this scenario, OpenLDAP allows the cluster owner to search for groups when assigning persmissions. Without OpenLDAP, the functionality to search for groups would not be supported.

    When a member of the OpenLDAP group logs in to Rancher, she is redirected to Shibboleth and enters her username and password.

    Shibboleth validates her credentials, and retrieves user attributes from OpenLDAP, including groups. Then Shibboleth sends a SAML assertion to Rancher including the user attributes. Rancher uses the group data so that she can access all of the resources and permissions that her groups have permissions for.

    Adding OpenLDAP Group Permissions to Rancher Resources

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html index 33879eafc96..a5b821447a5 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-cluster-drivers.html @@ -5,13 +5,13 @@ Cluster Drivers | Rancher Manager - +
    Version: v2.5

    Cluster Drivers

    Cluster drivers are used to create clusters in a hosted Kubernetes provider, such as Google GKE. The availability of which cluster driver to display when creating clusters is defined by the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters. By default, Rancher is packaged with several existing cloud provider cluster drivers, but you can also add custom cluster drivers to Rancher.

    If there are specific cluster drivers that you do not want to show your users, you may deactivate those cluster drivers within Rancher and they will not appear as an option for cluster creation.

    Managing Cluster Drivers​

    Prerequisites: To create, edit, or delete cluster drivers, you need one of the following permissions:

    Activating/Deactivating Cluster Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Google GKE, Amazon EKS and Azure AKS. If you want to show or hide any node driver, you can change its status.

    1. From the Global view, choose Tools > Drivers in the navigation bar.

    2. From the Drivers page, select the Cluster Drivers tab.

    3. Select the driver that you wish to Activate or Deactivate and select the appropriate icon.

    Adding Custom Cluster Drivers​

    If you want to use a cluster driver that Rancher doesn't support out-of-the-box, you can add the provider's driver in order to start using them to create hosted kubernetes clusters.

    1. From the Global view, choose Tools > Drivers in the navigation bar.

    2. From the Drivers page select the Cluster Drivers tab.

    3. Click Add Cluster Driver.

    4. Complete the Add Cluster Driver form. Then click Create.

    Developing your own Cluster Driver​

    In order to develop cluster driver to add to Rancher, please refer to our example.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html index 84ed64f8460..55725570a51 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-provisioning-drivers/manage-node-drivers.html @@ -5,13 +5,13 @@ Node Drivers | Rancher Manager - +
    Version: v2.5

    Node Drivers

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Managing Node Drivers​

    Prerequisites: To create, edit, or delete drivers, you need one of the following permissions:

    Activating/Deactivating Node Drivers​

    By default, Rancher only activates drivers for the most popular cloud providers, Amazon EC2, Azure, DigitalOcean and vSphere. If you want to show or hide any node driver, you can change its status.

    1. From the Global view, choose Tools > Drivers in the navigation bar. From the Drivers page, select the Node Drivers tab.

    2. Select the driver that you wish to Activate or Deactivate and select the appropriate icon.

    Adding Custom Node Drivers​

    If you want to use a node driver that Rancher doesn't support out-of-the-box, you can add that provider's driver in order to start using them to create node templates and eventually node pools for your Kubernetes cluster.

    1. From the Global view, choose Tools > Drivers in the navigation bar. From the Drivers page, select the Node Drivers tab.

    2. Click Add Node Driver.

    3. Complete the Add Node Driver form. Then click Create.

    Developing your own node driver​

    Node drivers are implemented with Docker Machine.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html index 12091bda8ef..f22bd38ad14 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/access-or-share-templates.html @@ -5,13 +5,13 @@ Access and Sharing | Rancher Manager - +
    Version: v2.5

    Access and Sharing

    If you are an RKE template owner, you can share it with users or groups of users, who can then use the template to create clusters.

    Since RKE templates are specifically shared with users and groups, owners can share different RKE templates with different sets of users.

    When you share a template, each user can have one of two access levels:

    • Owner: This user can update, delete, and share the templates that they own. The owner can also share the template with other users.
    • User: These users can create clusters using the template. They can also upgrade those clusters to new revisions of the same template. When you share a template as Make Public (read-only), all users in your Rancher setup have the User access level for the template.

    If you create a template, you automatically become an owner of that template.

    If you want to delegate responsibility for updating the template, you can share ownership of the template. For details on how owners can modify templates, refer to the documentation about revising templates.

    There are several ways to share templates:

    • Add users to a new RKE template during template creation
    • Add users to an existing RKE template
    • Make the RKE template public, sharing it with all users in the Rancher setup
    • Share template ownership with users who are trusted to modify the template

    Sharing Templates with Specific Users or Groups​

    To allow users or groups to create clusters using your template, you can give them the basic User access level for the template.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to share and click the ⋮ > Edit.
    3. In the Share Template section, click on Add Member.
    4. Search in the Name field for the user or group you want to share the template with.
    5. Choose the User access type.
    6. Click Save.

    Result: The user or group can create clusters using the template.

    Sharing Templates with All Users​

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to share and click the ⋮ > Edit.
    3. Under Share Template, click Make Public (read-only). Then click Save.

    Result: All users in the Rancher setup can create clusters using the template.

    Sharing Ownership of Templates​

    If you are the creator of a template, you might want to delegate responsibility for maintaining and updating a template to another user or group.

    In that case, you can give users the Owner access type, which allows another user to update your template, delete it, or share access to it with other users.

    To give Owner access to a user or group,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to share and click the ⋮ > Edit.
    3. Under Share Template, click on Add Member and search in the Name field for the user or group you want to share the template with.
    4. In the Access Type field, click Owner.
    5. Click Save.

    Result: The user or group has the Owner access type, and can modify, share, or delete the template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html index f684a8cd7ee..14736ac50e3 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/apply-templates.html @@ -5,13 +5,13 @@ Applying Templates | Rancher Manager - +
    Version: v2.5

    Applying Templates

    You can create a cluster from an RKE template that you created, or from a template that has been shared with you.

    RKE templates can be applied to new clusters.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    You can't change a cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Creating a Cluster from an RKE Template​

    To add a cluster hosted by an infrastructure provider using an RKE template, use these steps:

    1. From the Global view, go to the Clusters tab.
    2. Click Add Cluster and choose the infrastructure provider.
    3. Provide the cluster name and node template details as usual.
    4. To use an RKE template, under the Cluster Options, check the box for Use an existing RKE template and revision.
    5. Choose an existing template and revision from the dropdown menu.
    6. Optional: You can edit any settings that the RKE template owner marked as Allow User Override when the template was created. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template. Then you will need to edit the cluster to upgrade it to the new revision.
    7. Click Save to launch the cluster.

    Updating a Cluster Created with an RKE Template​

    When the template owner creates a template, each setting has a switch in the Rancher UI that indicates if users can override the setting.

    • If the setting allows a user override, you can update these settings in the cluster by editing the cluster.
    • If the switch is turned off, you cannot change these settings unless the cluster owner creates a template revision that lets you override them. If there are settings that you want to change, but don't have the option to, you will need to contact the template owner to get a new revision of the template.

    If a cluster was created from an RKE template, you can edit the cluster to update the cluster to a new revision of the template.

    An existing cluster's settings can be saved as an RKE template. In that situation, you can also edit the cluster to update the cluster to a new revision of the template.

    Note: You can't change the cluster to use a different RKE template. You can only update the cluster to a new revision of the same template.

    Converting an Existing Cluster to Use an RKE Template​

    This section describes how to create an RKE template from an existing cluster.

    RKE templates cannot be applied to existing clusters, except if you save an existing cluster's settings as an RKE template. This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to use a newer version of the template.

    To convert an existing cluster to use an RKE template,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that will be converted to use an RKE template. Click ⋮ > Save as RKE Template.
    3. Enter a name for the template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html index 18cc2c8350e..c223a1ae8aa 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/creator-permissions.html @@ -5,13 +5,13 @@ Template Creator Permissions | Rancher Manager - +
    Version: v2.5

    Template Creator Permissions

    Administrators have the permission to create RKE templates, and only administrators can give that permission to other users.

    For more information on administrator permissions, refer to the documentation on global permissions.

    Giving Users Permission to Create Templates

    Templates can only be created by users who have the global permission Create RKE Templates.

    Administrators have the global permission to create templates, and only administrators can give that permission to other users.

    For information on allowing users to modify existing templates, refer to Sharing Templates.

    Administrators can give users permission to create RKE templates in two ways:

    Allowing a User to Create Templates​

    An administrator can individually grant the role Create RKE Templates to any existing user by following these steps:

    1. From the global view, click the Users tab. Choose the user you want to edit and click the ⋮ > Edit.
    2. In the Global Permissions section, choose Custom and select the Create RKE Templates role along with any other roles the user should have. Click Save.

    Result: The user has permission to create RKE templates.

    Allowing New Users to Create Templates by Default​

    Alternatively, the administrator can give all new users the default permission to create RKE templates by following the following steps. This will not affect the permissions of existing users.

    1. From the Global view, click Security > Roles.
    2. Under the Global roles tab, go to the role Create RKE Templates and click the ⋮ > Edit.
    3. Select the option Yes: Default role for new users and click Save.

    Result: Any new user created in this Rancher installation will be able to create RKE templates. Existing users will not get this permission.

    Revoking Permission to Create Templates​

    Administrators can remove a user's permission to create templates with the following steps:

    1. From the global view, click the Users tab. Choose the user you want to edit and click the ⋮ > Edit.
    2. In the Global Permissions section, un-check the box for Create RKE Templates. In this section, you can change the user back to a standard user, or give the user a different set of custom permissions.
    3. Click Save.

    Result: The user cannot create RKE templates.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html index f918ef5cd56..c9229d4b1a0 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/enforce-templates.html @@ -5,13 +5,13 @@ Template Enforcement | Rancher Manager - +
    Version: v2.5

    Template Enforcement

    This section describes how template administrators can enforce templates in Rancher, restricting the ability of users to create clusters without a template.

    By default, any standard user in Rancher can create clusters. But when RKE template enforcement is turned on,

    • Only an administrator has the ability to create clusters without a template.
    • All standard users must use an RKE template to create a new cluster.
    • Standard users cannot create a cluster without using a template.

    Users can only create new templates if the administrator gives them permission.

    After a cluster is created with an RKE template, the cluster creator cannot edit settings that are defined in the template. The only way to change those settings after the cluster is created is to upgrade the cluster to a new revision of the same template. If cluster creators want to change template-defined settings, they would need to contact the template owner to get a new revision of the template. For details on how template revisions work, refer to the documentation on revising templates.

    Requiring New Clusters to Use an RKE Template​

    You might want to require new clusters to use a template to ensure that any cluster launched by a standard user will use the Kubernetes and/or Rancher settings that are vetted by administrators.

    To require new clusters to use an RKE template, administrators can turn on RKE template enforcement with the following steps:

    1. From the Global view, click the Settings tab.
    2. Go to the cluster-template-enforcement setting. Click the vertical ⋮ and click Edit.
    3. Set the value to True and click Save.

    Result: All clusters provisioned by Rancher must use a template, unless the creator is an administrator.

    Disabling RKE Template Enforcement​

    To allow new clusters to be created without an RKE template, administrators can turn off RKE template enforcement with the following steps:

    1. From the Global view, click the Settings tab.
    2. Go to the cluster-template-enforcement setting. Click the vertical ⋮ and click Edit.
    3. Set the value to False and click Save.

    Result: When clusters are provisioned by Rancher, they don't need to use a template.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html index 7ebc2d721e6..9179845ab2c 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/example-use-cases.html @@ -5,13 +5,13 @@ Example Scenarios | Rancher Manager - +
    Version: v2.5

    Example Scenarios

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    • Enforcing templates: Administrators might want to enforce one or more template settings for everyone if they want all new Rancher-provisioned clusters to have those settings.
    • Sharing different templates with different users: Administrators might give different templates to basic and advanced users, so that basic users have more restricted options and advanced users have more discretion when creating clusters.
    • Updating template settings: If an organization's security and DevOps teams decide to embed best practices into the required settings for new clusters, those best practices could change over time. If the best practices change, a template can be updated to a new revision and clusters created from the template can upgrade to the new version of the template.
    • Sharing ownership of a template: When a template owner no longer wants to maintain a template, or wants to delegate ownership of the template, this scenario describes how template ownership can be shared.

    Enforcing a Template Setting for Everyone​

    Let's say there is an organization in which the administrators decide that all new clusters should be created with Kubernetes version 1.14.

    1. First, an administrator creates a template which specifies the Kubernetes version as 1.14 and marks all other settings as Allow User Override.
    2. The administrator makes the template public.
    3. The administrator turns on template enforcement.

    Results:

    • All Rancher users in the organization have access to the template.
    • All new clusters created by standard users with this template will use Kubernetes 1.14 and they are unable to use a different Kubernetes version. By default, standard users don't have permission to create templates, so this template will be the only template they can use unless more templates are shared with them.
    • All standard users must use a cluster template to create a new cluster. They cannot create a cluster without using a template.

    In this way, the administrators enforce the Kubernetes version across the organization, while still allowing end users to configure everything else.

    Templates for Basic and Advanced Users​

    Let's say an organization has both basic and advanced users. Administrators want the basic users to be required to use a template, while the advanced users and administrators create their clusters however they want.

    1. First, an administrator turns on RKE template enforcement. This means that every standard user in Rancher will need to use an RKE template when they create a cluster.
    2. The administrator then creates two templates:
    • One template for basic users, with almost every option specified except for access keys
    • One template for advanced users, which has most or all options has Allow User Override turned on
    1. The administrator shares the advanced template with only the advanced users.
    2. The administrator makes the template for basic users public, so the more restrictive template is an option for everyone who creates a Rancher-provisioned cluster.

    Result: All Rancher users, except for administrators, are required to use a template when creating a cluster. Everyone has access to the restrictive template, but only advanced users have permission to use the more permissive template. The basic users are more restricted, while advanced users have more freedom when configuring their Kubernetes clusters.

    Updating Templates and Clusters Created with Them​

    Let's say an organization has a template that requires clusters to use Kubernetes v1.14. However, as time goes on, the administrators change their minds. They decide they want users to be able to upgrade their clusters to use newer versions of Kubernetes.

    In this organization, many clusters were created with a template that requires Kubernetes v1.14. Because the template does not allow that setting to be overridden, the users who created the cluster cannot directly edit that setting.

    The template owner has several options for allowing the cluster creators to upgrade Kubernetes on their clusters:

    • Specify Kubernetes v1.15 on the template: The template owner can create a new template revision that specifies Kubernetes v1.15. Then the owner of each cluster that uses that template can upgrade their cluster to a new revision of the template. This template upgrade allows the cluster creator to upgrade Kubernetes to v1.15 on their cluster.
    • Allow any Kubernetes version on the template: When creating a template revision, the template owner can also mark the the Kubernetes version as Allow User Override using the switch near that setting on the Rancher UI. This will allow clusters that upgrade to this template revision to use any version of Kubernetes.
    • Allow the latest minor Kubernetes version on the template: The template owner can also create a template revision in which the Kubernetes version is defined as Latest v1.14 (Allows patch version upgrades). This means clusters that use that revision will be able to get patch version upgrades, but major version upgrades will not be allowed.

    Allowing Other Users to Control and Share a Template​

    Let's say Alice is a Rancher administrator. She owns an RKE template that reflects her organization's agreed-upon best practices for creating a cluster.

    Bob is an advanced user who can make informed decisions about cluster configuration. Alice trusts Bob to create new revisions of her template as the best practices get updated over time. Therefore, she decides to make Bob an owner of the template.

    To share ownership of the template with Bob, Alice adds Bob as an owner of her template.

    The result is that as a template owner, Bob is in charge of version control for that template. Bob can now do all of the following:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html index ccbde133d8e..77ca5846b2e 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/infrastructure.html @@ -5,13 +5,13 @@ RKE Templates and Infrastructure | Rancher Manager - +
    Version: v2.5

    RKE Templates and Infrastructure

    In Rancher, RKE templates are used to provision Kubernetes and define Rancher settings, while node templates are used to provision nodes.

    Therefore, even if RKE template enforcement is turned on, the end user still has flexibility when picking the underlying hardware when creating a Rancher cluster. The end users of an RKE template can still choose an infrastructure provider and the nodes they want to use.

    If you want to standardize the hardware in your clusters, use RKE templates conjunction with node templates or with a server provisioning tool such as Terraform.

    Node Templates​

    Node templates are responsible for node configuration and node provisioning in Rancher. From your user profile, you can set up node templates to define which templates are used in each of your node pools. With node pools enabled, you can make sure you have the required number of nodes in each node pool, and ensure that all nodes in the pool are the same.

    Terraform​

    Terraform is a server provisioning tool. It uses infrastructure-as-code that lets you create almost every aspect of your infrastructure with Terraform configuration files. It can automate the process of server provisioning in a way that is self-documenting and easy to track in version control.

    This section focuses on how to use Terraform with the Rancher 2 Terraform provider, which is a recommended option to standardize the hardware for your Kubernetes clusters. If you use the Rancher Terraform provider to provision hardware, and then use an RKE template to provision a Kubernetes cluster on that hardware, you can quickly create a comprehensive, production-ready cluster.

    Terraform allows you to:

    • Define almost any kind of infrastructure-as-code, including servers, databases, load balancers, monitoring, firewall settings, and SSL certificates
    • Leverage catalog apps and multi-cluster apps
    • Codify infrastructure across many platforms, including Rancher and major cloud providers
    • Commit infrastructure-as-code to version control
    • Easily repeat configuration and setup of infrastructure
    • Incorporate infrastructure changes into standard development practices
    • Prevent configuration drift, in which some servers become configured differently than others

    How Does Terraform Work?​

    Terraform is written in files with the extension .tf. It is written in HashiCorp Configuration Language, which is a declarative language that lets you define the infrastructure you want in your cluster, the cloud provider you are using, and your credentials for the provider. Then Terraform makes API calls to the provider in order to efficiently create that infrastructure.

    To create a Rancher-provisioned cluster with Terraform, go to your Terraform configuration file and define the provider as Rancher 2. You can set up your Rancher 2 provider with a Rancher API key. Note: The API key has the same permissions and access level as the user it is associated with.

    Then Terraform calls the Rancher API to provision your infrastructure, and Rancher calls the infrastructure provider. As an example, if you wanted to use Rancher to provision infrastructure on AWS, you would provide both your Rancher API key and your AWS credentials in the Terraform configuration file or in environment variables so that they could be used to provision the infrastructure.

    When you need to make changes to your infrastructure, instead of manually updating the servers, you can make changes in the Terraform configuration files. Then those files can be committed to version control, validated, and reviewed as necessary. Then when you run terraform apply, the changes would be deployed.

    Tips for Working with Terraform​

    • There are examples of how to provide most aspects of a cluster in the documentation for the Rancher 2 provider.

    • In the Terraform settings, you can install Docker Machine by using the Docker Machine node driver.

    • You can also modify auth in the Terraform provider.

    • You can reverse engineer how to do define a setting in Terraform by changing the setting in Rancher, then going back and checking your Terraform state file to see how it maps to the current state of your infrastructure.

    • If you want to manage Kubernetes cluster settings, Rancher settings, and hardware settings all in one place, use Terraform modules. You can pass a cluster configuration YAML file or an RKE template configuration file to a Terraform module so that the Terraform module will create it. In that case, you could use your infrastructure-as-code to manage the version control and revision history of both your Kubernetes cluster and its underlying hardware.

    Tip for Creating CIS Benchmark Compliant Clusters​

    This section describes one way that you can make security and compliance-related config files standard in your clusters.

    When you create a CIS benchmark compliant cluster, you have an encryption config file and an audit log config file.

    Your infrastructure provisioning system can write those files to disk. Then in your RKE template, you would specify where those files will be, then add your encryption config file and audit log config file as extra mounts to the kube-api-server.

    Then you would make sure that the kube-api-server flag in your RKE template uses your CIS-compliant config files.

    In this way, you can create flags that comply with the CIS benchmark.

    Resources​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html index 39a353f6a95..601c5221622 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/manage-rke1-templates.html @@ -5,14 +5,14 @@ Creating and Revising Templates | Rancher Manager - +
    Version: v2.5

    Creating and Revising Templates

    This section describes how to manage RKE templates and revisions. You an create, share, update, and delete templates from the Global view under Tools > RKE Templates.

    Template updates are handled through a revision system. When template owners want to change or update a template, they create a new revision of the template. Individual revisions cannot be edited. However, if you want to prevent a revision from being used to create a new cluster, you can disable it.

    Template revisions can be used in two ways: to create a new cluster, or to upgrade a cluster that was created with an earlier version of the template. The template creator can choose a default revision, but when end users create a cluster, they can choose any template and any template revision that is available to them. After the cluster is created from a specific revision, it cannot change to another template, but the cluster can be upgraded to a newer available revision of the same template.

    The template owner has full control over template revisions, and can create new revisions to update the template, delete or disable revisions that should not be used to create clusters, and choose which template revision is the default.

    Prerequisites​

    You can create RKE templates if you have the Create RKE Templates permission, which can be given by an administrator.

    You can revise, share, and delete a template if you are an owner of the template. For details on how to become an owner of a template, refer to the documentation on sharing template ownership.

    Creating a Template​

    1. From the Global view, click Tools > RKE Templates.
    2. Click Add Template.
    3. Provide a name for the template. An auto-generated name is already provided for the template' first version, which is created along with this template.
    4. Optional: Share the template with other users or groups by adding them as members. You can also make the template public to share with everyone in the Rancher setup.
    5. Then follow the form on screen to save the cluster configuration parameters as part of the template's revision. The revision can be marked as default for this template.

    Result: An RKE template with one revision is configured. You can use this RKE template revision later when you provision a Rancher-launched cluster. After a cluster is managed by an RKE template, it cannot be disconnected and the option to uncheck Use an existing RKE Template and Revision will be unavailable.

    Updating a Template​

    When you update an RKE template, you are creating a revision of the existing template. Clusters that were created with an older version of the template can be updated to match the new revision.

    You can't edit individual revisions. Since you can't edit individual revisions of a template, in order to prevent a revision from being used, you can disable it.

    When new template revisions are created, clusters using an older revision of the template are unaffected.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template that you want to edit and click the ⋮ > Edit.
    3. Edit the required information and click Save.
    4. Optional: You can change the default revision of this template and also change who it is shared with.

    Result: The template is updated. To apply it to a cluster using an older version of the template, refer to the section on upgrading a cluster to use a new revision of a template.

    Deleting a Template​

    When you no longer use an RKE template for any of your clusters, you can delete it.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to delete and click the ⋮ > Delete.
    3. Confirm the deletion when prompted.

    Result: The template is deleted.

    Creating a Revision Based on the Default Revision​

    You can clone the default template revision and quickly update its settings rather than creating a new revision from scratch. Cloning templates saves you the hassle of re-entering the access keys and other parameters needed for cluster creation.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template that you want to clone and click the ⋮ > New Revision From Default.
    3. Complete the rest of the form to create a new revision.

    Result: The RKE template revision is cloned and configured.

    Creating a Revision Based on a Cloned Revision​

    When creating new RKE template revisions from your user settings, you can clone an existing revision and quickly update its settings rather than creating a new one from scratch. Cloning template revisions saves you the hassle of re-entering the cluster parameters.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to clone. Then select ⋮ > Clone Revision.
    3. Complete the rest of the form.

    Result: The RKE template revision is cloned and configured. You can use the RKE template revision later when you provision a cluster. Any existing cluster using this RKE template can be upgraded to this new revision.

    Disabling a Template Revision​

    When you no longer want an RKE template revision to be used for creating new clusters, you can disable it. A disabled revision can be re-enabled.

    You can disable the revision if it is not being used by any cluster.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to disable. Then select ⋮ > Disable.

    Result: The RKE template revision cannot be used to create a new cluster.

    Re-enabling a Disabled Template Revision​

    If you decide that a disabled RKE template revision should be used to create new clusters, you can re-enable it.

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the template revision you want to re-enable. Then select ⋮ > Enable.

    Result: The RKE template revision can be used to create a new cluster.

    Setting a Template Revision as Default​

    When end users create a cluster using an RKE template, they can choose which revision to create the cluster with. You can configure which revision is used by default.

    To set an RKE template revision as default,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template revision that should be default and click the ⋮ > Set as Default.

    Result: The RKE template revision will be used as the default option when clusters are created with the template.

    Deleting a Template Revision​

    You can delete all revisions of a template except for the default revision.

    To permanently delete a revision,

    1. From the Global view, click Tools > RKE Templates.
    2. Go to the RKE template revision that should be deleted and click the ⋮ > Delete.

    Result: The RKE template revision is deleted.

    Upgrading a Cluster to Use a New Template Revision​

    This section assumes that you already have a cluster that has an RKE template applied. This section also assumes that you have updated the template that the cluster is using so that a new template revision is available.

    To upgrade a cluster to use a new template revision,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that you want to upgrade and click ⋮ > Edit.
    3. In the Cluster Options section, click the dropdown menu for the template revision, then select the new template revision.
    4. Click Save.

    Result: The cluster is upgraded to use the settings defined in the new template revision.

    Exporting a Running Cluster to a New RKE Template and Revision​

    You can save an existing cluster's settings as an RKE template.

    This exports the cluster's settings as a new RKE template, and also binds the cluster to that template. The result is that the cluster can only be changed if the template is updated, and the cluster is upgraded to [use a newer version of the template.]

    To convert an existing cluster to use an RKE template,

    1. From the Global view in Rancher, click the Clusters tab.
    2. Go to the cluster that will be converted to use an RKE template. Click ⋮ > Save as RKE Template.
    3. Enter a name for the template in the form that appears, and click Create.

    Results:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html index 782672fe8dd..eb3e3f186e1 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-rke1-templates/override-template-settings.html @@ -5,13 +5,13 @@ Overriding Template Settings | Rancher Manager - +
    Version: v2.5

    Overriding Template Settings

    When a user creates an RKE template, each setting in the template has a switch in the Rancher UI that indicates if users can override the setting. This switch marks those settings as Allow User Override.

    After a cluster is created with a template, end users can't update any of the settings defined in the template unless the template owner marked them as Allow User Override. However, if the template is updated to a new revision that changes the settings or allows end users to change them, the cluster can be upgraded to a new revision of the template and the changes in the new revision will be applied to the cluster.

    When any parameter is set as Allow User Override on the RKE template, it means that end users have to fill out those fields during cluster creation and they can edit those settings afterward at any time.

    The Allow User Override model of the RKE template is useful for situations such as:

    • Administrators know that some settings will need the flexibility to be frequently updated over time
    • End users will need to enter their own access keys or secret keys, for example, cloud credentials or credentials for backup snapshots
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html index fb635a1d147..68c3523dead 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.html @@ -5,13 +5,13 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.5

    Pod Security Policies

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification (like root privileges).

    If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message of Pod <NAME> is forbidden: unable to validate....

    How PSPs Work​

    You can assign PSPs at the cluster or project level.

    PSPs work through inheritance:

    • By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
    • Exception: Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
    • You can override the default PSP by assigning a different PSP directly to the project.

    Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Read more about Pod Security Policies in the Kubernetes Documentation.

    Default PSPs​

    Rancher ships with two default Pod Security Policies (PSPs): the restricted and unrestricted policies.

    Restricted​

    This policy is based on the Kubernetes example restricted policy. It significantly restricts what types of pods can be deployed to a cluster or project. This policy:

    • Prevents pods from running as a privileged user and prevents escalation of privileges.
    • Validates that server-required security mechanisms are in place (such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.

    Unrestricted​

    This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.

    Creating PSPs​

    Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.

    Requirements​

    Rancher can only assign PSPs for clusters that are launched using RKE.

    You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by editing the cluster.

    It is a best practice to set PSP at the cluster level.

    We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.

    Creating PSPs in the Rancher UI​

    1. From the Global view, select Security > Pod Security Policies from the main menu. Then click Add Policy.

      Step Result: The Add Policy form opens.

    2. Name the policy.

    3. Complete each section of the form. Refer to the Kubernetes documentation for more information on what each policy does.

    Configuration​

    The Kubernetes documentation on PSPs is here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html index 194e9c623b5..4250af76332 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/global-default-private-registry.html @@ -5,13 +5,13 @@ Configuring a Global Default Private Registry | Rancher Manager - +
    Version: v2.5

    Configuring a Global Default Private Registry

    You might want to use a private container registry to share your custom base images within your organization. With a private registry, you can keep a private, consistent, and centralized source of truth for the container images that are used in your clusters.

    There are two main ways to set up private registries in Rancher: by setting up the global default registry through the Settings tab in the global view, and by setting up a private registry in the advanced options in the cluster-level settings. The global default registry is intended to be used for air-gapped setups, for registries that do not require credentials. The cluster-level private registry is intended to be used in all setups in which the private registry requires credentials.

    This section is about configuring the global default private registry, and focuses on how to configure the registry from the Rancher UI after Rancher is installed.

    For instructions on setting up a private registry with command line options during the installation of Rancher, refer to the air gapped Kubernetes installation instructions.

    If your private registry requires credentials, it cannot be used as the default registry. There is no global way to set up a private registry with authorization for every Rancher-provisioned cluster. Therefore, if you want a Rancher-provisioned cluster to pull images from a private registry with credentials, you will have to pass in the registry credentials through the advanced cluster options every time you create a new cluster.

    Setting a Private Registry with No Credentials as the Default Registry​

    1. Log into Rancher and configure the default administrator password.

    2. Go into the Settings view.

    3. Look for the setting called system-default-registry and choose Edit.

    4. Change the value to your registry (e.g. registry.yourdomain.com:port). Do not prefix the registry with http:// or https://.

    Result: Rancher will use your private registry to pull system images.

    Setting a Private Registry with Credentials when Deploying a Cluster​

    You can follow these steps to configure a private registry when you provision a cluster with Rancher:

    1. When you create a cluster through the Rancher UI, go to the Cluster Options section and click Show Advanced Options.
    2. In the Enable Private Registries section, click Enabled.
    3. Enter the registry URL and credentials.
    4. Click Save.

    Result: The new cluster will be able to pull images from the private registry.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html index ce576756c08..4dce2bae92d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.html @@ -5,14 +5,14 @@ Cluster and Project Roles | Rancher Manager - +
    Version: v2.5

    Cluster and Project Roles

    Cluster and project roles define user authorization inside a cluster or project. You can manage these roles from the Global > Security > Roles page.

    Membership and Role Assignment​

    The projects and clusters accessible to non-administrative users is determined by membership. Membership is a list of users who have access to a specific cluster or project based on the roles they were assigned in that cluster or project. Each cluster and project includes a tab that a user with the appropriate permissions can use to manage membership.

    When you create a cluster or project, Rancher automatically assigns you as the Owner for it. Users assigned the Owner role can assign other users roles in the cluster or project.

    Note: Non-administrative users cannot access any existing projects/clusters by default. A user with appropriate permissions (typically the owner) must explicitly assign the project and cluster membership.

    Cluster Roles​

    Cluster roles are roles that you can assign to users, granting them access to a cluster. There are two primary cluster roles: Owner and Member.

    • Cluster Owner:

      These users have full control over the cluster and all resources in it.

    • Cluster Member:

      These users can view most cluster level resources and create new projects.

    Custom Cluster Roles​

    Rancher lets you assign custom cluster roles to a standard user instead of the typical Owner or Member roles. These roles can be either a built-in custom cluster role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a cluster. See the table below for a list of built-in custom cluster roles.

    Cluster Role Reference​

    The following table lists each built-in custom cluster role available and whether that level of access is included in the default cluster-level permissions, Cluster Owner and Cluster Member.

    Built-in Cluster RoleOwnerMember
    Create Projects✓✓
    Manage Cluster Backups            ✓
    Manage Cluster Catalogs✓
    Manage Cluster Members✓
    Manage Nodes✓
    Manage Storage✓
    View All Projects✓
    View Cluster Catalogs✓✓
    View Cluster Members✓✓
    View Nodes✓✓

    For details on how each cluster role can access Kubernetes resources, you can go to the Global view in the Rancher UI. Then click Security > Roles and go to the Clusters tab. If you click an individual role, you can refer to the Grant Resources table to see all of the operations and resources that are permitted by the role.

    Note: When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Giving a Custom Cluster Role to a Cluster Member​

    After an administrator sets up a custom cluster role, cluster owners and admins can then assign those roles to cluster members.

    To assign a custom role to a new cluster member, you can use the Rancher UI. To modify the permissions of an existing member, you will need to use the Rancher API view.

    To assign the role to a new cluster member,

    1. Go to the Cluster view, then go to the Members tab.
    2. Click Add Member. Then in the Cluster Permissions section, choose the custom cluster role that should be assigned to the member.
    3. Click Create.

    Result: The member has the assigned role.

    To assign any custom role to an existing cluster member,

    1. Go to the member you want to give the role to. Click the ⋮ > View in API.
    2. In the roleTemplateId field, go to the drop-down menu and choose the role you want to assign to the member. Click Show Request and Send Request.

    Result: The member has the assigned role.

    Project Roles​

    Project roles are roles that can be used to grant users access to a project. There are three primary project roles: Owner, Member, and Read Only.

    • Project Owner:

      These users have full control over the project and all resources in it.

    • Project Member:

      These users can manage project-scoped resources like namespaces and workloads, but cannot manage other project members.

      Note:

      By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Read Only:

      These users can view everything in the project but cannot create, update, or delete anything.

      Caveat:

      Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the owner or member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    Custom Project Roles​

    Rancher lets you assign custom project roles to a standard user instead of the typical Owner, Member, or Read Only roles. These roles can be either a built-in custom project role or one defined by a Rancher administrator. They are convenient for defining narrow or specialized access for a standard user within a project. See the table below for a list of built-in custom project roles.

    Project Role Reference​

    The following table lists each built-in custom project role available in Rancher and whether it is also granted by the Owner, Member, or Read Only role.

    Built-in Project RoleOwnerMemberRead Only
    Manage Project Members✓
    Create Namespaces✓✓
    Manage Config Maps✓✓
    Manage Ingress✓✓
    Manage Project Catalogs✓
    Manage Secrets✓✓
    Manage Service Accounts✓✓
    Manage Services✓✓
    Manage Volumes✓✓
    Manage Workloads✓✓
    View Secrets✓✓
    View Config Maps✓✓✓
    View Ingress✓✓✓
    View Project Members✓✓✓
    View Project Catalogs✓✓✓
    View Service Accounts✓✓✓
    View Services✓✓✓
    View Volumes✓✓✓
    View Workloads✓✓✓

    Notes:

    • Each project role listed above, including Owner, Member, and Read Only, is comprised of multiple rules granting access to various resources. You can view the roles and their rules on the Global > Security > Roles page.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.
    • The Manage Project Members role allows the project owner to manage any members of the project and grant them any project scoped role regardless of their access to the project resources. Be cautious when assigning this role out individually.

    Defining Custom Roles​

    As previously mentioned, custom roles can be defined for use at the cluster or project level. The context field defines whether the role will appear on the cluster member page, project member page, or both.

    When defining a custom role, you can grant access to specific resources or specify roles from which the custom role should inherit. A custom role can be made up of a combination of specific grants and inherited roles. All grants are additive. This means that defining a narrower grant for a specific resource will not override a broader grant defined in a role that the custom role is inheriting from.

    Default Cluster and Project Roles​

    By default, when a standard user creates a new cluster or project, they are automatically assigned an ownership role: either cluster owner or project owner. However, in some organizations, these roles may overextend administrative access. In this use case, you can change the default role to something more restrictive, such as a set of individual roles or a custom role.

    There are two methods for changing default cluster/project roles:

    • Assign Custom Roles: Create a custom role for either your cluster or project, and then set the custom role as default.

    • Assign Individual Roles: Configure multiple cluster/project roles as default for assignment to the creating user.

      For example, instead of assigning a role that inherits other roles (such as cluster owner), you can choose a mix of individual roles (such as manage nodes and manage storage).

    Note:

    • Although you can lock a default role, the system still assigns the role to users who create a cluster/project.
    • Only users that create clusters/projects inherit their roles. Users added to the cluster/project membership afterward must be explicitly assigned their roles.

    Configuring Default Roles for Cluster and Project Creators​

    You can change the cluster or project role(s) that are automatically assigned to the creating user.

    1. From the Global view, select Security > Roles from the main menu. Select either the Cluster or Project tab.

    2. Find the custom or individual role that you want to use as default. Then edit the role by selecting ⋮ > Edit.

    3. Enable the role as default.

    For Clusters
    1. From Cluster Creator Default, choose Yes: Default role for new cluster creation.
    2. Click Save.
    For Projects
    1. From **Project Creator Default**, choose **Yes: Default role for new project creation**. 1. Click **Save**.
    1. If you want to remove a default role, edit the permission and select No from the default roles option.

    Result: The default roles are configured based on your changes. Roles assigned to cluster/project creators display a check in the Cluster/Project Creator Default column.

    Cluster Membership Revocation Behavior​

    When you revoke the cluster membership for a standard user that's explicitly assigned membership to both the cluster and a project within the cluster, that standard user loses their cluster roles but retains their project roles. In other words, although you have revoked the user's permissions to access the cluster and its nodes, the standard user can still:

    If you want to completely revoke a user's access within a cluster, revoke both their cluster and project memberships.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html index 4526b58b4c5..cac48f83d3b 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/custom-roles.html @@ -5,13 +5,13 @@ Custom Roles | Rancher Manager - +
    Version: v2.5

    Custom Roles

    Within Rancher, roles determine what actions a user can make within a cluster or project.

    Note that roles are different from permissions, which determine what clusters and projects you can access.

    It is possible for a custom role to enable privilege escalation. For details, see this section.

    Prerequisites​

    To complete the tasks on this page, one of the following permissions are required:

    Creating A Custom Role for a Cluster or Project​

    While Rancher comes out-of-the-box with a set of default user roles, you can also create default custom roles to provide users with very specific permissions within Rancher.

    The steps to add custom roles differ depending on the version of Rancher.

    1. From the Global view, select Security > Roles from the main menu.

    2. Select a tab to determine the scope of the roles you're adding. The tabs are:

    • Cluster: The role is valid for assignment when adding/managing members to only clusters.
    • Project: The role is valid for assignment when adding/managing members to only projects.

    1. Click Add Cluster/Project Role.

    2. Name the role.

    3. Optional: Choose the Cluster/Project Creator Default option to assign this role to a user when they create a new cluster or project. Using this feature, you can expand or restrict the default roles for cluster/project creators.

      Out of the box, the Cluster Creator Default and the Project Creator Default roles are Cluster Owner and Project Owner respectively.

    4. Use the Grant Resources options to assign individual Kubernetes API endpoints to the role.

      When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

      You can also choose the individual cURL methods (Create, Delete, Get, etc.) available for use with each endpoint you assign.

    5. Use the Inherit from a Role options to assign individual Rancher roles to your custom roles. Note: When a custom role inherits from a parent role, the parent role cannot be deleted until the child role is deleted.

    6. Click Create.

    Creating a Custom Global Role​

    Creating a Custom Global Role that Copies Rules from an Existing Role​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role in which all of the rules from another role, such as the administrator role, are copied into a new role. This allows you to only configure the variations between the existing role and the new role.

    The custom global role can then be assigned to a user or group so that the custom global role takes effect the first time the user or users sign into Rancher.

    To create a custom global role based on an existing role,

    1. Go to the Global view and click Security > Roles.

    2. On the Global tab, go to the role that the custom global role will be based on. Click ⋮ (…) > Clone.

    3. Enter a name for the role.

    4. Optional: To assign the custom role default for new users, go to the New User Default section and click Yes: Default role for new users.

    5. In the Grant Resources section, select the Kubernetes resource operations that will be enabled for users with the custom role.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

    6. Click Save.

    Creating a Custom Global Role that Does Not Copy Rules from Another Role​

    Custom global roles don't have to be based on existing roles. To create a custom global role by choosing the specific Kubernetes resource operations that should be allowed for the role, follow these steps:

    1. Go to the Global view and click Security > Roles.

    2. On the Global tab, click Add Global Role.

    3. Enter a name for the role.

    4. Optional: To assign the custom role default for new users, go to the New User Default section and click Yes: Default role for new users.

    5. In the Grant Resources section, select the Kubernetes resource operations that will be enabled for users with the custom role.

      The Resource text field provides a method to search for pre-defined Kubernetes API resources, or enter a custom resource name for the grant. The pre-defined or (Custom) resource must be selected from the dropdown, after entering a resource name into this field.

    6. Click Save.

    Deleting a Custom Global Role​

    When deleting a custom global role, all global role bindings with this custom role are deleted.

    If a user is only assigned one custom global role, and the role is deleted, the user would lose access to Rancher. For the user to regain access, an administrator would need to edit the user and apply new global permissions.

    Custom global roles can be deleted, but built-in roles cannot be deleted.

    To delete a custom global role,

    1. Go to the Global view and click Security > Roles.
    2. On the Global tab, go to the custom global role that should be deleted and click ⋮ (…) > Delete.
    3. Click Delete.

    Assigning a Custom Global Role to a Group​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to create a custom global role. When the role is assigned to a group, the users in the group have the appropriate level of access the first time they sign into Rancher.

    When a user in the group logs in, they get the built-in Standard User global role by default. They will also get the permissions assigned to their groups.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have their individual Standard User role.

    Prerequisites: You can only assign a global role to a group if:

    To assign a custom global role to a group, follow these steps:

    1. From the Global view, go to Security > Groups.
    2. Click Assign Global Role.
    3. In the Select Group To Add field, choose the existing group that will be assigned the custom global role.
    4. In the Custom section, choose any custom global role that will be assigned to the group.
    5. Optional: In the Global Permissions or Built-in sections, select any additional permissions that the group should have.
    6. Click Create.

    Result: The custom global role will take effect when the users in the group log into Rancher.

    Privilege Escalation​

    The Configure Catalogs custom permission is powerful and should be used with caution. When an admin assigns the Configure Catalogs permission to a standard user, it could result in privilege escalation in which the user could give themselves admin access to Rancher provisioned clusters. Anyone with this permission should be considered equivalent to an admin.

    The Manager Users role grants the ability to create, update, and delete any user. This presents the risk of privilege escalation as even non-admin users with this role will be able to create, update, and delete admin users. Admins should take caution when assigning this role.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html index 429a5cc33f2..d8170b1d281 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/global-permissions.html @@ -5,13 +5,13 @@ Global Permissions | Rancher Manager - +
    Version: v2.5

    Global Permissions

    Permissions are individual access rights that you can assign when selecting a custom permission for a user.

    Global Permissions define user authorization outside the scope of any particular cluster. Out-of-the-box, there are three default global permissions: Administrator, Standard User and User-base.

    • Administrator: These users have full control over the entire Rancher system and all clusters within it.

    • **Standard User:** These users can create new clusters and use them. Standard users can also assign other users permissions to their clusters.

    • User-Base: User-Base users have login-access only.

    You cannot update or delete the built-in Global Permissions.

    Restricted Admin

    A new restricted-admin role was created in Rancher v2.5 in order to prevent privilege escalation from the local Rancher server Kubernetes cluster. This role has full administrator access to all downstream clusters managed by Rancher, but it does not have permission to alter the local Kubernetes cluster.

    The restricted-admin can create other restricted-admin users with an equal level of access.

    A new setting was added to Rancher to set the initial bootstrapped administrator to have the restricted-admin role. This applies to the first user created when the Rancher server is started for the first time. If the environment variable is set, then no global administrator would be created, and it would be impossible to create the global administrator through Rancher.

    To bootstrap Rancher with the restricted-admin as the initial user, the Rancher server should be started with the following environment variable:

    CATTLE_RESTRICTED_DEFAULT_ADMIN=true

    List of restricted-admin Permissions​

    The permissions for the restricted-admin role differ based on the Rancher version.

    The restricted-admin permissions are as follows:

    • Has full admin access to all downstream clusters managed by Rancher.
    • Can add other users and assign them to clusters outside of the local cluster.
    • Can create other restricted admins.

    Upgrading from Rancher with a Hidden Local Cluster​

    Before Rancher v2.5, it was possible to run the Rancher server using this flag to hide the local cluster:

    --add-local=false

    You will need to drop this flag when upgrading to Rancher v2.5. Otherwise, Rancher will not start. The restricted-admin role can be used to continue restricting access to the local cluster.

    Changing Global Administrators to Restricted Admins​

    If Rancher already has a global administrator, they should change all global administrators over to the new restricted-admin role.

    This can be done through Security > Users and moving any Administrator role over to Restricted Administrator.

    Signed-in users can change themselves over to the restricted-admin if they wish, but they should only do that as the last step, otherwise they won't have the permissions to do so.

    Global Permission Assignment

    Global permissions for local users are assigned differently than users who log in to Rancher using external authentication.

    Global Permissions for New Local Users​

    When you create a new local user, you assign them a global permission as you complete the Add User form.

    To see the default permissions for new users, go to the Global view and click Security > Roles. On the Global tab, there is a column named New User Default. When adding a new local user, the user receives all default global permissions that are marked as checked in this column. You can change the default global permissions to meet your needs.

    Global Permissions for Users with External Authentication​

    When a user logs into Rancher using an external authentication provider for the first time, they are automatically assigned the New User Default global permissions. By default, Rancher assigns the Standard User permission for new users.

    To see the default permissions for new users, go to the Global view and click Security > Roles. On the Global tab, there is a column named New User Default. When adding a new local user, the user receives all default global permissions that are marked as checked in this column, and you can change them to meet your needs.

    Permissions can be assigned to an individual user with these steps.

    You can assign a role to everyone in the group at the same time if the external authentication provider supports groups.

    Custom Global Permissions

    Using custom permissions is convenient for providing users with narrow or specialized access to Rancher.

    When a user from an external authentication source signs into Rancher for the first time, they're automatically assigned a set of global permissions (hereafter, permissions). By default, after a user logs in for the first time, they are created as a user and assigned the default user permission. The standard user permission allows users to login and create clusters.

    However, in some organizations, these permissions may extend too much access. Rather than assigning users the default global permissions of Administrator or Standard User, you can assign them a more restrictive set of custom global permissions.

    The default roles, Administrator and Standard User, each come with multiple global permissions built into them. The Administrator role includes all global permissions, while the default user role includes three global permissions: Create Clusters, Use Catalog Templates, and User Base, which is equivalent to the minimum permission to log in to Rancher. In other words, the custom global permissions are modularized so that if you want to change the default user role permissions, you can choose which subset of global permissions are included in the new default user role.

    Administrators can enforce custom global permissions in multiple ways:

    Custom Global Permissions Reference​

    The following table lists each custom global permission available and whether it is included in the default global permissions, Administrator, Standard User and User-Base.

    Custom Global PermissionAdministratorStandard UserUser-Base
    Create Clusters✓✓
    Create RKE Templates✓✓
    Manage Authentication✓
    Manage Catalogs✓
    Manage Cluster Drivers✓
    Manage Node Drivers✓
    Manage PodSecurityPolicy Templates✓
    Manage Roles✓
    Manage Settings✓
    Manage Users✓
    Use Catalog Templates✓✓
    User Base* (Basic log-in access)✓✓

    *This role has two names:

    • When you go to the Users tab and edit a user's global role, this role is called Login Access in the custom global permissions list.
    • When you go to the Security tab and edit the roles from the roles page, this role is called User Base.

    For details on which Kubernetes resources correspond to each global permission, you can go to the Global view in the Rancher UI. Then click Security > Roles and go to the Global tab. If you click an individual role, you can refer to the Grant Resources table to see all of the operations and resources that are permitted by the role.

    Notes:

    • Each permission listed above is comprised of multiple individual permissions not listed in the Rancher UI. For a full list of these permissions and the rules they are comprised of, access through the API at /v3/globalRoles.
    • When viewing the resources associated with default roles created by Rancher, if there are multiple Kubernetes API resources on one line item, the resource will have (Custom) appended to it. These are not custom resources but just an indication that there are multiple Kubernetes API resources as one resource.

    Configuring Default Global Permissions​

    If you want to restrict the default permissions for new users, you can remove the user permission as default role and then assign multiple individual permissions as default instead. Conversely, you can also add administrative permissions on top of a set of other standard permissions.

    Note: Default roles are only assigned to users added from an external authentication provider. For local users, you must explicitly assign global permissions when adding a user to Rancher. You can customize these global permissions when adding the user.

    To change the default global permissions that are assigned to external users upon their first log in, follow these steps:

    1. From the Global view, select Security > Roles from the main menu. Make sure the Global tab is selected.

    2. Find the permissions set that you want to add or remove as a default. Then edit the permission by selecting ⋮ > Edit.

    3. If you want to add the permission as a default, Select Yes: Default role for new users and then click Save.

    4. If you want to remove a default permission, edit the permission and select No from New User Default.

    Result: The default global permissions are configured based on your changes. Permissions assigned to new users display a check in the New User Default column.

    Configuring Global Permissions for Individual Users​

    To configure permission for a user,

    1. Go to the Users tab.

    2. On this page, go to the user whose access level you want to change and click ⋮ > Edit.

    3. In the Global Permissions section, click Custom.

    4. Check the boxes for each subset of permissions you want the user to have access to.

    5. Click Save.

    Result: The user's global permissions have been updated.

    Configuring Global Permissions for Groups​

    If you have a group of individuals that need the same level of access in Rancher, it can save time to assign permissions to the entire group at once, so that the users in the group have the appropriate level of access the first time they sign into Rancher.

    After you assign a custom global role to a group, the custom global role will be assigned to a user in the group when they log in to Rancher.

    For existing users, the new permissions will take effect when the users log out of Rancher and back in again, or when an administrator refreshes the group memberships.

    For new users, the new permissions take effect when the users log in to Rancher for the first time. New users from this group will receive the permissions from the custom global role in addition to the New User Default global permissions. By default, the New User Default permissions are equivalent to the Standard User global role, but the default permissions can be configured.

    If a user is removed from the external authentication provider group, they would lose their permissions from the custom global role that was assigned to the group. They would continue to have any remaining roles that were assigned to them, which would typically include the roles marked as New User Default. Rancher will remove the permissions that are associated with the group when the user logs out, or when an administrator refreshes group memberships, whichever comes first.

    Prerequisites: You can only assign a global role to a group if:

    To assign a custom global role to a group, follow these steps:

    1. From the Global view, go to Security > Groups.
    2. Click Assign Global Role.
    3. In the Select Group To Add field, choose the existing group that will be assigned the custom global role.
    4. In the Global Permissions, Custom, and/or Built-in sections, select the permissions that the group should have.
    5. Click Create.

    Result: The custom global role will take effect when the users in the group log into Rancher.

    Refreshing Group Memberships​

    When an administrator updates the global permissions for a group, the changes take effect for individual group members after they log out of Rancher and log in again.

    To make the changes take effect immediately, an administrator or cluster owner can refresh group memberships.

    An administrator might also want to refresh group memberships if a user is removed from a group in the external authentication service. In that case, the refresh makes Rancher aware that the user was removed from the group.

    To refresh group memberships,

    1. From the Global view, click Security > Users.
    2. Click Refresh Group Memberships.

    Result: Any changes to the group members' permissions will take effect.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html index 0b83c592da1..a7332b0c56f 100644 --- a/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html +++ b/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/locked-roles.html @@ -5,13 +5,13 @@ Locked Roles | Rancher Manager - +
    Version: v2.5

    Locked Roles

    You can set roles to a status of locked. Locking roles prevent them from being assigned users in the future.

    Locked roles:

    • Cannot be assigned to users that don't already have it assigned.

    • Are not listed in the Member Roles drop-down when you are adding a user to a cluster or project.

    • Do not affect users assigned the role before you lock the role. These users retain access that the role provides.

      Example: let's say your organization creates an internal policy that users assigned to a cluster are prohibited from creating new projects. It's your job to enforce this policy.

      To enforce it, before you add new users to the cluster, you should lock the following roles: Cluster Owner, Cluster Member, and Create Projects. Then you could create a new custom role that includes the same permissions as a Cluster Member, except the ability to create projects. Then, you use this new custom role when adding users to a cluster.

    Roles can be locked by the following users:

    • Any user assigned the Administrator global permission.
    • Any user assigned the Custom Users permission, along with the Manage Roles role.

    Locking/Unlocking Roles​

    If you want to prevent a role from being assigned to users, you can set it to a status of locked.

    You can lock roles in two contexts:

    1. From the Global view, select Security > Roles.

    2. From the role that you want to lock (or unlock), select ⋮ > Edit.

    3. From the Locked option, choose the Yes or No radio button. Then click Save.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html index 662f3c8482a..795eeeb424d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/configure-alerts-for-periodic-scan-on-a-schedule.html @@ -5,13 +5,13 @@ Configure Alerts for Periodic Scan on a Schedule | Rancher Manager - +
    Version: v2.5

    Configure Alerts for Periodic Scan on a Schedule

    It is possible to run a ClusterScan on a schedule.

    A scheduled scan can also specify if you should receive alerts when the scan completes.

    Alerts are supported only for a scan that runs on a schedule.

    The CIS Benchmark application supports two types of alerts:

    • Alert on scan completion: This alert is sent out when the scan run finishes. The alert includes details including the ClusterScan's name and the ClusterScanProfile name.
    • Alert on scan failure: This alert is sent out if there are some test failures in the scan run or if the scan is in a Fail state.
    Prerequisite

    Before enabling alerts for rancher-cis-benchmark, make sure to install the rancher-monitoring application and configure the Receivers and Routes. For more information, see this section.

    While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan. An example route configuration is here.

    To configure alerts for a scan that runs on a schedule,

    1. Please enable alerts on the rancher-cis-benchmark application (#enabling-alerting-for-rancher-cis-benchmark)
    2. In the upper left corner, click ☰ > Cluster Management.
    3. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    4. Click CIS Benchmark > Scan.
    5. Click Create.
    6. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    7. Choose the option Run scan on a schedule.
    8. Enter a valid cron schedule expression in the field Schedule.
    9. Check the boxes next to the Alert types under Alerting.
    10. Optional: Choose a Retention Count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
    11. Click Create.

    Result: The scan runs and reschedules to run according to the cron schedule provided. Alerts are sent out when the scan finishes if routes and receiver are configured under rancher-monitoring application.

    A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html index a8b038f5eb2..18b59ceb376 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/create-a-custom-benchmark-version-to-run.html @@ -5,13 +5,13 @@ Create a Custom Benchmark Version for Running a Cluster Scan | Rancher Manager - +
    Version: v2.5

    Create a Custom Benchmark Version for Running a Cluster Scan

    There could be some Kubernetes cluster setups that require custom configurations of the Benchmark tests. For example, the path to the Kubernetes config files or certs might be different than the standard location where the upstream CIS Benchmarks look for them.

    It is now possible to create a custom Benchmark Version for running a cluster scan using the rancher-cis-benchmark application.

    For details, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html index 91cae9d8702..ca2209ec3b9 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/enable-alerting-for-rancher-cis-benchmark.html @@ -5,14 +5,14 @@ Enable Alerting for Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.5

    Enable Alerting for Rancher CIS Benchmark

    Alerts can be configured to be sent out for a scan that runs on a schedule.

    Prerequisite:

    Before enabling alerts for rancher-cis-benchmark, make sure to install the rancher-monitoring application and configure the Receivers and Routes. For more information, see this section. While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan. An example route configuration is here.

    While installing or upgrading the rancher-cis-benchmark Helm chart, set the following flag to true in the values.yaml:

    alerts:
      enabled: true
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html index c5764bcae51..288158ed5f5 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.html @@ -5,13 +5,13 @@ Install Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.5

    Install Rancher CIS Benchmark

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to install CIS Benchmark and click Explore.
    3. In the left navigation bar, click Apps & Marketplace > Charts.
    4. Click CIS Benchmark
    5. Click Install.

    Result: The CIS scan application is deployed on the Kubernetes cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html index 6e981a01783..0abd9ab5f04 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan-periodically-on-a-schedule.html @@ -5,13 +5,13 @@ Run a Scan Periodically on a Schedule | Rancher Manager - +
    Version: v2.5

    Run a Scan Periodically on a Schedule

    To run a ClusterScan on a schedule,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    5. Choose the option Run scan on a schedule.
    6. Enter a valid cron schedule expression in the field Schedule.
    7. Choose a Retention count, which indicates the number of reports maintained for this recurring scan. By default this count is 3. When this retention limit is reached, older reports will get purged.
    8. Click Create.

    Result: The scan runs and reschedules to run according to the cron schedule provided. The Next Scan value indicates the next time this scan will run again.

    A report is generated with the scan results every time the scan runs. To see the latest results, click the name of the scan that appears.

    You can also see the previous reports by choosing the report from the Reports dropdown on the scan detail page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html index 1da73ac849c..a9639e8f240 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/run-a-scan.html @@ -5,13 +5,13 @@ Run a Scan | Rancher Manager - +
    Version: v2.5

    Run a Scan

    When a ClusterScan custom resource is created, it launches a new CIS scan on the cluster for the chosen ClusterScanProfile.

    note

    There is currently a limitation of running only one CIS scan at a time for a cluster. If you create multiple ClusterScan custom resources, they will be run one after the other by the operator, and until one scan finishes, the rest of the ClusterScan custom resources will be in the "Pending" state.

    To run a scan,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. Click Create.
    5. Choose a cluster scan profile. The profile determines which CIS Benchmark version will be used and which tests will be performed. If you choose the Default profile, then the CIS Operator will choose a profile applicable to the type of Kubernetes cluster it is installed on.
    6. Click Create.

    Result: A report is generated with the scan results. To see the results, click the name of the scan that appears.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html index 445b88f9be4..ac06fb1dc7a 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/skip-tests.html @@ -5,13 +5,13 @@ Skip Tests | Rancher Manager - +
    Version: v2.5

    Skip Tests

    CIS scans can be run using test profiles with user-defined skips.

    To skip tests, you will create a custom CIS scan profile. A profile contains the configuration for the CIS scan, which includes the benchmark versions to use and any specific tests to skip in that benchmark.

    1. In the upper left corner, click ☰ > Cluster Management.

    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.

    3. Click CIS Benchmark > Profile.

    4. From here, you can create a profile in multiple ways. To make a new profile, click Create and fill out the form in the UI. To make a new profile based on an existing profile, go to the existing profile and click ⋮ Clone. If you are filling out the form, add the tests to skip using the test IDs, using the relevant CIS Benchmark as a reference. If you are creating the new test profile as YAML, you will add the IDs of the tests to skip in the skipTests directive. You will also give the profile a name:

      apiVersion: cis.cattle.io/v1
      kind: ClusterScanProfile
      metadata:
        annotations:
          meta.helm.sh/release-name: clusterscan-operator
          meta.helm.sh/release-namespace: cis-operator-system
        labels:
          app.kubernetes.io/managed-by: Helm
        name: "<example-profile>"
      spec:
        benchmarkVersion: cis-1.5
        skipTests:
          - "1.1.20"
          - "1.1.21"

    5. Click Create.

    Result: A new CIS scan profile is created.

    When you run a scan that uses this profile, the defined tests will be skipped during the scan. The skipped tests will be marked in the generated report as Skip.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html index ea01f24c27d..b08a3b03e3d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/uninstall-rancher-cis-benchmark.html @@ -5,13 +5,13 @@ Uninstall Rancher CIS Benchmark | Rancher Manager - +
    Version: v2.5

    Uninstall Rancher CIS Benchmark

    1. From the Cluster Dashboard, go to the left navigation bar and click Apps & Marketplace > Installed Apps.
    2. Go to the cis-operator-system namespace and check the boxes next to rancher-cis-benchmark-crd and rancher-cis-benchmark.
    3. Click Delete and confirm Delete.

    Result: The rancher-cis-benchmark application is uninstalled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html index 29a783d2acd..1bc28d77d83 100644 --- a/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html +++ b/v2.5/how-to-guides/advanced-user-guides/cis-scan-guides/view-reports.html @@ -5,13 +5,13 @@ View Reports | Rancher Manager - +
    Version: v2.5

    View Reports

    To view the generated CIS scan reports,

    1. In the upper left corner, click ☰ > Cluster Management.
    2. On the Clusters page, go to the cluster where you want to run a CIS scan and click Explore.
    3. Click CIS Benchmark > Scan.
    4. The Scans page will show the generated reports. To see a detailed report, go to a scan report and click the name.

    One can download the report from the Scans list or from the scan detail page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html index d9d8543ba7a..67db3e8b351 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.html @@ -5,13 +5,13 @@ 1. Enable Istio in the Cluster | Rancher Manager - +
    Version: v2.5

    1. Enable Istio in the Cluster

    Prerequisites:

    • Only a user with the cluster-admin Kubernetes default role assigned can configure and install Istio in a Kubernetes cluster.
    • If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see this section.
    • To install Istio on an RKE2 cluster, additional steps are required. For details, see this section.
    • To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see this section.
    1. From the Cluster Explorer, navigate to available Charts in Apps & Marketplace
    2. Select the Istio chart from the rancher provided charts
    3. If you have not already installed your own monitoring app, you will be prompted to install the rancher-monitoring app. Optional: Set your Selector or Scrape config options on rancher-monitoring app install.
    4. Optional: Configure member access and resource limits for the Istio components. Ensure you have enough resources on your worker nodes to enable Istio.
    5. Optional: Make additional configuration changes to values.yaml if needed.
    6. Optional: Add additional resources or configuration via the overlay file.
    7. Click Install.

    Result: Istio is installed at the cluster level.

    Additional Config Options

    For more information on configuring Istio, refer to the configuration reference.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html index cc62c911d54..04d909d5fbb 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-namespace.html @@ -5,13 +5,13 @@ 2. Enable Istio in a Namespace | Rancher Manager - +
    Version: v2.5

    2. Enable Istio in a Namespace

    You will need to manually enable Istio in each namespace that you want to be tracked or controlled by Istio. When Istio is enabled in a namespace, the Envoy sidecar proxy will be automatically injected into all new workloads that are deployed in the namespace.

    This namespace setting will only affect new workloads in the namespace. Any preexisting workloads will need to be re-deployed to leverage the sidecar auto injection.

    Prerequisite: To enable Istio in a namespace, the cluster must have Istio installed.

    1. In the Rancher Cluster Explorer, open the kubectl shell.
    2. Then run kubectl label namespace <namespace> istio-injection=enabled

    Result: The namespace now has the label istio-injection=enabled. All new workloads deployed in this namespace will have the Istio sidecar injected by default.

    Verifying that Automatic Istio Sidecar Injection is Enabled​

    To verify that Istio is enabled, deploy a hello-world workload in the namespace. Go to the workload and click the pod name. In the Containers section, you should see the istio-proxy container.

    Excluding Workloads from Being Injected with the Istio Sidecar​

    If you need to exclude a workload from getting injected with the Istio sidecar, use the following annotation on the workload:

    sidecar.istio.io/inject: “false”

    To add the annotation to a workload,

    1. From the Cluster Explorer view, use the side-nav to select the Overview page for workloads.
    2. Go to the workload that should not have the sidecar and edit as yaml
    3. Add the following key, value sidecar.istio.io/inject: false as an annotation on the workload
    4. Click Save.

    Result: The Istio sidecar will not be injected into the workload.

    NOTE: If you are having issues with a Job you deployed not completing, you will need to add this annotation to your pod using the provided steps. Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed.

    Next: Select the Nodes ​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html index 34215a2d0f4..e6a6f15babe 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/generate-and-view-traffic.html @@ -5,13 +5,13 @@ 6. Generate and View Traffic | Rancher Manager - +
    Version: v2.5

    6. Generate and View Traffic

    This section describes how to view the traffic that is being managed by Istio.

    The Kiali Traffic Graph

    The Istio overview page provides a link to the Kiali dashboard. From the Kiali dashboard, you are able to view graphs for each namespace. The Kiali graph provides a powerful way to visualize the topology of your Istio service mesh. It shows you which services communicate with each other.

    Prerequisite: To enable traffic to show up in the graph, ensure you have prometheus installed in the cluster. Rancher-istio installs Kiali configured by default to work with the rancher-monitoring chart. You can use rancher-monitoring or install your own monitoring solution. Optional: you can change configuration on how data scraping occurs by setting the Selectors & Scrape Configs options.

    To see the traffic graph,

    1. From the Cluster Explorer, select Istio from the nav dropdown.
    2. Click the Kiali link on the Istio Overview page.
    3. Click on Graph in the side nav.
    4. Change the namespace in the Namespace dropdown to view the traffic for each namespace.

    If you refresh the URL to the BookInfo app several times, you should be able to see green arrows on the Kiali graph showing traffic to v1 and v3 of the reviews service. The control panel on the right side of the graph lets you configure details including how many minutes of the most recent traffic should be shown on the graph.

    For additional tools and visualizations, you can go to Grafana, and Prometheus dashboards from the Monitoring Overview page

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html index 789105952c3..39604b1ad73 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-istio-gateway.html @@ -5,13 +5,13 @@ 4. Set up the Istio Gateway | Rancher Manager - +
    Version: v2.5

    4. Set up the Istio Gateway

    The gateway to each cluster can have its own port or load balancer, which is unrelated to a service mesh. By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster.

    You can use the Nginx Ingress controller with or without Istio installed. If this is the only gateway to your cluster, Istio will be able to route traffic from service to service, but Istio will not be able to receive traffic from outside the cluster.

    To allow Istio to receive external traffic, you need to enable Istio's gateway, which works as a north-south proxy for external traffic. When you enable the Istio gateway, the result is that your cluster will have two Ingresses.

    You will also need to set up a Kubernetes gateway for your services. This Kubernetes resource points to Istio's implementation of the ingress gateway to the cluster.

    You can route traffic into the service mesh with a load balancer or use Istio's NodePort gateway. This section describes how to set up the NodePort gateway.

    For more information on the Istio gateway, refer to the Istio documentation.

    In an Istio-enabled cluster, you can have two Ingresses: the default Nginx Ingress, and the default Istio controller.

    Enable an Istio Gateway

    The ingress gateway is a Kubernetes service that will be deployed in your cluster. The Istio Gateway allows for more extensive customization and flexibility.

    1. From the Cluster Explorer, select Istio from the nav dropdown.
    2. Click Gateways in the side nav bar.
    3. Click Create from Yaml.
    4. Paste your Istio Gateway yaml, or Read from File.
    5. Click Create.

    Result: The gateway is deployed, and will now route traffic with applied rules

    Example Istio Gateway

    We add the BookInfo app deployments in services when going through the Workloads example. Next we add an Istio Gateway so that the app is accessible from outside your cluster.

    1. From the Cluster Explorer, select Istio from the nav dropdown.
    2. Click Gateways in the side nav bar.
    3. Click Create from Yaml.
    4. Copy and paste the Gateway yaml provided below.
    5. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: Gateway
    metadata:
      name: bookinfo-gateway
    spec:
      selector:
        istio: ingressgateway # use istio default controller
      servers:
      - port:
          number: 80
          name: http
          protocol: HTTP
        hosts:
        - "*"
    ---

    Then to deploy the VirtualService that provides the traffic routing for the Gateway

    1. Click VirtualService in the side nav bar.
    2. Click Create from Yaml.
    3. Copy and paste the VirtualService yaml provided below.
    4. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: bookinfo
    spec:
      hosts:
      - "*"
      gateways:
      - bookinfo-gateway
      http:
      - match:
        - uri:
            exact: /productpage
        - uri:
            prefix: /static
        - uri:
            exact: /login
        - uri:
            exact: /logout
        - uri:
            prefix: /api/v1/products
        route:
        - destination:
            host: productpage
            port:
              number: 9080

    Result: You have configured your gateway resource so that Istio can receive traffic from outside the cluster.

    Confirm that the resource exists by running:

    kubectl get gateway -A

    The result should be something like this:

    NAME               AGE
    bookinfo-gateway   64m

    Access the ProductPage Service from a Web Browser​

    To test and see if the BookInfo app deployed correctly, the app can be viewed a web browser using the Istio controller IP and port, combined with the request name specified in your Kubernetes gateway resource:

    http://<IP of Istio controller>:<Port of istio controller>/productpage

    To get the ingress gateway URL and port,

    1. From the Cluster Explorer, Click on Workloads > Overview.
    2. Scroll down to the istio-system namespace.
    3. Within istio-system, there is a workload named istio-ingressgateway. Under the name of this workload, you should see links, such as 80/tcp.
    4. Click one of those links. This should show you the URL of the ingress gateway in your web browser. Append /productpage to the URL.

    Result: You should see the BookInfo app in the web browser.

    For help inspecting the Istio controller URL and ports, try the commands the Istio documentation.

    Troubleshooting

    The official Istio documentation suggests kubectl commands to inspect the correct ingress host and ingress port for external requests.

    Confirming that the Kubernetes Gateway Matches Istio's Ingress Controller​

    You can try the steps in this section to make sure the Kubernetes gateway is configured properly.

    In the gateway resource, the selector refers to Istio's default ingress controller by its label, in which the key of the label is istio and the value is ingressgateway. To make sure the label is appropriate for the gateway, do the following:

    1. From the Cluster Explorer, Click on Workloads > Overview.
    2. Scroll down to the istio-system namespace.
    3. Within istio-system, there is a workload named istio-ingressgateway. Click the name of this workload and go to the Labels and Annotations section. You should see that it has the key istio and the value ingressgateway. This confirms that the selector in the Gateway resource matches Istio's default ingress controller.

    Next: Set up Istio's Components for Traffic Management​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html index 647fe6fce20..0106a37fa2e 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/set-up-traffic-management.html @@ -5,13 +5,13 @@ 5. Set up Istio's Components for Traffic Management | Rancher Manager - +
    Version: v2.5

    5. Set up Istio's Components for Traffic Management

    A central advantage of traffic management in Istio is that it allows dynamic request routing. Some common applications for dynamic request routing include canary deployments and blue/green deployments. The two key resources in Istio traffic management are virtual services and destination rules.

    • Virtual services intercept and direct traffic to your Kubernetes services, allowing you to divide percentages of traffic from a request to different services. You can use them to define a set of routing rules to apply when a host is addressed.
    • Destination rules serve as the single source of truth about which service versions are available to receive traffic from virtual services. You can use these resources to define policies that apply to traffic that is intended for a service after routing has occurred.

    This section describes how to add an example virtual service that corresponds to the reviews microservice in the sample BookInfo app. The purpose of this service is to divide traffic between two versions of the reviews service.

    In this example, we take the traffic to the reviews service and intercept it so that 50 percent of it goes to v1 of the service and 50 percent goes to v2.

    After this virtual service is deployed, we will generate traffic and see from the Kiali visualization that traffic is being routed evenly between the two versions of the service.

    To deploy the virtual service and destination rules for the reviews service,

    1. From the Cluster Explorer, select Istio from the nav dropdown.
    2. Click DestinationRule in the side nav bar.
    3. Click Create from Yaml.
    4. Copy and paste the DestinationRule yaml provided below.
    5. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: DestinationRule
    metadata:
      name: reviews
    spec:
      host: reviews
      subsets:
      - name: v1
        labels:
          version: v1
      - name: v2
        labels:
          version: v2
      - name: v3
        labels:
          version: v3

    Then to deploy the VirtualService that provides the traffic routing that utilizes the DestinationRule

    1. Click VirtualService in the side nav bar.
    2. Click Create from Yaml.
    3. Copy and paste the VirtualService yaml provided below.
    4. Click Create.
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: reviews
    spec:
      hosts:
      - reviews
      http:
      - route:
        - destination:
            host: reviews
            subset: v1
          weight: 50
        - destination:
            host: reviews
            subset: v3
          weight: 50
    ---

    Result: When you generate traffic to this service (for example, by refreshing the ingress gateway URL), the Kiali traffic graph will reflect that traffic to the reviews service is divided evenly between v1 and v3.

    Next: Generate and View Traffic​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html index 8b65786fa4d..81e6980d446 100644 --- a/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html +++ b/v2.5/how-to-guides/advanced-user-guides/istio-setup-guide/use-istio-sidecar.html @@ -5,13 +5,13 @@ 3. Add Deployments and Services with the Istio Sidecar | Rancher Manager - +
    Version: v2.5

    3. Add Deployments and Services with the Istio Sidecar

    Prerequisite: To enable Istio for a workload, the cluster and namespace must have the Istio app installed.

    Enabling Istio in a namespace only enables automatic sidecar injection for new workloads. To enable the Envoy sidecar for existing workloads, you need to enable it manually for each workload.

    To inject the Istio sidecar on an existing workload in the namespace, from the Cluster Explorer go to the workload, click the ⋮, and click Redeploy. When the workload is redeployed, it will have the Envoy sidecar automatically injected.

    Wait a few minutes for the workload to upgrade to have the istio sidecar. Click it and go to the Containers section. You should be able to see istio-proxy alongside your original workload. This means the Istio sidecar is enabled for the workload. Istio is doing all the wiring for the sidecar envoy. Now Istio can do all the features automatically if you enable them in the yaml.

    Add Deployments and Services​

    There are a few ways to add new Deployments in your namespace

    1. From the Cluster Explorer click on Workload > Overview.
    2. Click Create.
    3. Select Deployment from the various workload options.
    4. Fill out the form, or Edit as Yaml.
    5. Click Create.

    Alternatively, you can select the specific workload you want to deploy from the Workload section of the left navigation bar and create it from there.

    To add a Service to your namespace

    1. From the Cluster Explorer click on Service Discovery > Services
    2. Click Create
    3. Select the type of service you want to create from the various options
    4. Fill out the form, or Edit as Yaml
    5. Click Create

    You can also create deployments and services using the kubectl shell

    1. Run kubectl create -f <name of service/deployment file>.yaml if your file is stored locally in the cluster
    2. Or run cat<< EOF | kubectl apply -f -, paste the file contents into the terminal, then run EOF to complete the command.

    Example Deployments and Services​

    Next we add the Kubernetes resources for the sample deployments and services for the BookInfo app in Istio's documentation.

    1. From the Cluster Explorer, open the kubectl shell
    2. Run cat<< EOF | kubectl apply -f -
    3. Copy the below resources into the the shell
    4. Run EOF

    This will set up the following sample resources from Istio's example BookInfo app:

    Details service and deployment:

    • A details Service
    • A ServiceAccount for bookinfo-details
    • A details-v1 Deployment

    Ratings service and deployment:

    • A ratings Service
    • A ServiceAccount for bookinfo-ratings
    • A ratings-v1 Deployment

    Reviews service and deployments (three versions):

    • A reviews Service
    • A ServiceAccount for bookinfo-reviews
    • A reviews-v1 Deployment
    • A reviews-v2 Deployment
    • A reviews-v3 Deployment

    Productpage service and deployment:

    This is the main page of the app, which will be visible from a web browser. The other services will be called from this page.

    • A productpage service
    • A ServiceAccount for bookinfo-productpage
    • A productpage-v1 Deployment

    Resource YAML​

    # Copyright 2017 Istio Authors
    #
    #   Licensed under the Apache License, Version 2.0 (the "License");
    #   you may not use this file except in compliance with the License.
    #   You may obtain a copy of the License at
    #
    #       http://www.apache.org/licenses/LICENSE-2.0
    #
    #   Unless required by applicable law or agreed to in writing, software
    #   distributed under the License is distributed on an "AS IS" BASIS,
    #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    #   See the License for the specific language governing permissions and
    #   limitations under the License.

    ##################################################################################################
    # Details service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: details
      labels:
        app: details
        service: details
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: details
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-details
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: details-v1
      labels:
        app: details
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: details
          version: v1
      template:
        metadata:
          labels:
            app: details
            version: v1
        spec:
          serviceAccountName: bookinfo-details
          containers:
          - name: details
            image: docker.io/istio/examples-bookinfo-details-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Ratings service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: ratings
      labels:
        app: ratings
        service: ratings
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: ratings
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-ratings
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: ratings-v1
      labels:
        app: ratings
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: ratings
          version: v1
      template:
        metadata:
          labels:
            app: ratings
            version: v1
        spec:
          serviceAccountName: bookinfo-ratings
          containers:
          - name: ratings
            image: docker.io/istio/examples-bookinfo-ratings-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Reviews service
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: reviews
      labels:
        app: reviews
        service: reviews
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: reviews
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-reviews
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v1
      labels:
        app: reviews
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v1
      template:
        metadata:
          labels:
            app: reviews
            version: v1
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v2
      labels:
        app: reviews
        version: v2
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v2
      template:
        metadata:
          labels:
            app: reviews
            version: v2
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v2:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: reviews-v3
      labels:
        app: reviews
        version: v3
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: reviews
          version: v3
      template:
        metadata:
          labels:
            app: reviews
            version: v3
        spec:
          serviceAccountName: bookinfo-reviews
          containers:
          - name: reviews
            image: docker.io/istio/examples-bookinfo-reviews-v3:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---
    ##################################################################################################
    # Productpage services
    ##################################################################################################
    apiVersion: v1
    kind: Service
    metadata:
      name: productpage
      labels:
        app: productpage
        service: productpage
    spec:
      ports:
      - port: 9080
        name: http
      selector:
        app: productpage
    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: bookinfo-productpage
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: productpage-v1
      labels:
        app: productpage
        version: v1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: productpage
          version: v1
      template:
        metadata:
          labels:
            app: productpage
            version: v1
        spec:
          serviceAccountName: bookinfo-productpage
          containers:
          - name: productpage
            image: docker.io/istio/examples-bookinfo-productpage-v1:1.15.0
            imagePullPolicy: IfNotPresent
            ports:
            - containerPort: 9080
    ---

    Next: Set up the Istio Gateway​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html index 48552593991..aa31f4688d4 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/add-users-to-clusters.html @@ -5,14 +5,14 @@ Adding Users to Clusters | Rancher Manager - +
    Version: v2.5

    Adding Users to Clusters

    If you want to provide a user with access and permissions to all projects, nodes, and resources within a cluster, assign the user a cluster membership.

    Tip: Want to provide a user with access to a specific project within a cluster? See Adding Project Members instead.

    There are two contexts where you can add cluster members:

    • Adding Members to a New Cluster

      You can add members to a cluster as you create it (recommended if possible).

    • Adding Members to an Existing Cluster

      You can always add members to a cluster after a cluster is provisioned.

    Editing Cluster Membership​

    Cluster administrators can edit the membership for a cluster, controlling which Rancher users can access the cluster and what features they can use.

    1. From the Global view, open the cluster that you want to add members to.

    2. From the main menu, select Members. Then click Add Member.

    3. Search for the user or group that you want to add to the cluster.

      If external authentication is configured:

    4. Assign the user or group Cluster roles.

      What are Cluster Roles?

      Tip: For Custom Roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the cluster.

    • To revoke cluster membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the cluster, delete them from the cluster, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html index 24a851c72e7..89252b79a80 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.html @@ -5,13 +5,13 @@ How the Authorized Cluster Endpoint Works | Rancher Manager - +
    Version: v2.5

    How the Authorized Cluster Endpoint Works

    This section describes how the kubectl CLI, the kubeconfig file, and the authorized cluster endpoint work together to allow you to access a downstream Kubernetes cluster directly, without authenticating through the Rancher server. It is intended to provide background information and context to the instructions for how to set up kubectl to directly access a cluster.

    About the kubeconfig File​

    The kubeconfig file is a file used to configure access to Kubernetes when used in conjunction with the kubectl command line tool (or other clients).

    This kubeconfig file and its contents are specific to the cluster you are viewing. It can be downloaded from the cluster view in Rancher. You will need a separate kubeconfig file for each cluster that you have access to in Rancher.

    After you download the kubeconfig file, you will be able to use the kubeconfig file and its Kubernetes contexts to access your downstream cluster.

    If admins have enforced TTL on kubeconfig tokens, the kubeconfig file requires rancher cli to be present in your PATH.

    Two Authentication Methods for RKE Clusters​

    If the cluster is not an RKE cluster, the kubeconfig file allows you to access the cluster in only one way: it lets you be authenticated with the Rancher server, then Rancher allows you to run kubectl commands on the cluster.

    For RKE clusters, the kubeconfig file allows you to be authenticated in two ways:

    • Through the Rancher server authentication proxy: Rancher's authentication proxy validates your identity, then connects you to the downstream cluster that you want to access.
    • Directly with the downstream cluster's API server: RKE clusters have an authorized cluster endpoint enabled by default. This endpoint allows you to access your downstream Kubernetes cluster with the kubectl CLI and a kubeconfig file, and it is enabled by default for RKE clusters. In this scenario, the downstream cluster's Kubernetes API server authenticates you by calling a webhook (the kube-api-auth microservice) that Rancher set up.

    This second method, the capability to connect directly to the cluster's Kubernetes API server, is important because it lets you access your downstream cluster if you can't connect to Rancher.

    To use the authorized cluster endpoint, you will need to configure kubectl to use the extra kubectl context in the kubeconfig file that Rancher generates for you when the RKE cluster is created. This file can be downloaded from the cluster view in the Rancher UI, and the instructions for configuring kubectl are on this page.

    These methods of communicating with downstream Kubernetes clusters are also explained in the architecture page in the larger context of explaining how Rancher works and how Rancher communicates with downstream clusters.

    About the kube-api-auth Authentication Webhook​

    The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint, which is only available for RKE clusters. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

    During cluster provisioning, the file /etc/kubernetes/kube-api-authn-webhook.yaml is deployed and kube-apiserver is configured with --authentication-token-webhook-config-file=/etc/kubernetes/kube-api-authn-webhook.yaml. This configures the kube-apiserver to query http://127.0.0.1:6440/v1/authenticate to determine authentication for bearer tokens.

    The scheduling rules for kube-api-auth are listed below:

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    kube-api-authbeta.kubernetes.io/os:NotIn:windows
    node-role.kubernetes.io/controlplane:In:"true"    		noneoperator:Exists
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html index 03596a5dcc6..9dd5635bca0 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/access-clusters/use-kubectl-and-kubeconfig.html @@ -5,13 +5,13 @@ Access a Cluster with Kubectl and kubeconfig | Rancher Manager - +
    Version: v2.5

    Access a Cluster with Kubectl and kubeconfig

    This section describes how to manipulate your downstream Kubernetes cluster with kubectl from the Rancher UI or from your workstation.

    For more information on using kubectl, see Kubernetes Documentation: Overview of kubectl.

    Accessing Clusters with kubectl Shell in the Rancher UI​

    You can access and manage your clusters by logging into Rancher and opening the kubectl shell in the UI. No further configuration necessary.

    1. From the Global view, open the cluster that you want to access with kubectl.

    2. Click Launch kubectl. Use the window that opens to interact with your Kubernetes cluster.

    Accessing Clusters with kubectl from Your Workstation​

    This section describes how to download your cluster's kubeconfig file, launch kubectl from your workstation, and access your downstream cluster.

    This alternative method of accessing the cluster allows you to authenticate with Rancher and manage your cluster without using the Rancher UI.

    Prerequisites: These instructions assume that you have already created a Kubernetes cluster, and that kubectl is installed on your workstation. For help installing kubectl, refer to the official Kubernetes documentation.

    1. Log into Rancher. From the Global view, open the cluster that you want to access with kubectl.
    2. Click Kubeconfig File.
    3. Copy the contents displayed to your clipboard.
    4. Paste the contents into a new file on your local computer. Move the file to ~/.kube/config. Note: The default location that kubectl uses for the kubeconfig file is ~/.kube/config, but you can use any directory and specify it using the --kubeconfig flag, as in this command:
      kubectl --kubeconfig /custom/path/kube.config get pods
    5. From your workstation, launch kubectl. Use it to interact with your kubernetes cluster.

    Note on Resources Created Using kubectl​

    Rancher will discover and show resources created by kubectl. However, these resources might not have all the necessary annotations on discovery. If an operation (for instance, scaling the workload) is done to the resource using the Rancher UI/API, this may trigger recreation of the resources due to the missing annotations. This should only happen the first time an operation is done to the discovered resource.

    Authenticating Directly with a Downstream Cluster​

    This section intended to help you set up an alternative method to access an RKE cluster.

    This method is only available for RKE clusters that have the authorized cluster endpoint enabled. When Rancher creates this RKE cluster, it generates a kubeconfig file that includes additional kubectl context(s) for accessing your cluster. This additional context allows you to use kubectl to authenticate with the downstream cluster without authenticating through Rancher. For a longer explanation of how the authorized cluster endpoint works, refer to this page.

    We recommend that as a best practice, you should set up this method to access your RKE cluster, so that just in case you can’t connect to Rancher, you can still access the cluster.

    Prerequisites: The following steps assume that you have created a Kubernetes cluster and followed the steps to connect to your cluster with kubectl from your workstation.

    To find the name of the context(s) in your downloaded kubeconfig file, run:

    kubectl config get-contexts --kubeconfig /custom/path/kube.config
    CURRENT   NAME                        CLUSTER                     AUTHINFO     NAMESPACE
    *         my-cluster                  my-cluster                  user-46tmn
              my-cluster-controlplane-1   my-cluster-controlplane-1   user-46tmn

    In this example, when you use kubectl with the first context, my-cluster, you will be authenticated through the Rancher server.

    With the second context, my-cluster-controlplane-1, you would authenticate with the authorized cluster endpoint, communicating with an downstream RKE cluster directly.

    We recommend using a load balancer with the authorized cluster endpoint. For details, refer to the recommended architecture section.

    Now that you have the name of the context needed to authenticate directly with the cluster, you can pass the name of the context in as an option when running kubectl commands. The commands will differ depending on whether your cluster has an FQDN defined. Examples are provided in the sections below.

    When kubectl works normally, it confirms that you can access your cluster while bypassing Rancher's authentication proxy.

    Connecting Directly to Clusters with FQDN Defined​

    If an FQDN is defined for the cluster, a single context referencing the FQDN will be created. The context will be named <CLUSTER_NAME>-fqdn. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-fqdn get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-fqdn get pods

    Connecting Directly to Clusters without FQDN Defined​

    If there is no FQDN defined for the cluster, extra contexts will be created referencing the IP address of each node in the control plane. Each context will be named <CLUSTER_NAME>-<NODE_NAME>. When you want to use kubectl to access this cluster without Rancher, you will need to use this context.

    Assuming the kubeconfig file is located at ~/.kube/config:

    kubectl --context <CLUSTER_NAME>-<NODE_NAME> get nodes

    Directly referencing the location of the kubeconfig file:

    kubectl --kubeconfig /custom/path/kube.config --context <CLUSTER_NAME>-<NODE_NAME> get pods
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html index 9f01de69319..25ec5d5acf9 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/add-a-pod-security-policy.html @@ -5,13 +5,13 @@ Adding a Pod Security Policy | Rancher Manager - +
    Version: v2.5

    Adding a Pod Security Policy

    Prerequisite: The options below are available only for clusters that are launched using RKE.

    When your cluster is running pods with security-sensitive configurations, assign it a pod security policy, which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running.

    You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster.

    1. From the Global view, find the cluster to which you want to apply a pod security policy. Select ⋮ > Edit.

    2. Expand Cluster Options.

    3. From Pod Security Policy Support, select Enabled.

      Note: This option is only available for clusters provisioned by RKE.

    4. From the Default Pod Security Policy drop-down, select the policy you want to apply to the cluster.

      Rancher ships with policies of restricted and unrestricted, although you can create custom policies as well.

    5. Click Save.

    Result: The pod security policy is applied to the cluster and any projects within the cluster.

    Note: Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run.

    To check if a running workload passes your pod security policy, clone or upgrade it.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html index 0f4aa76eaa4..c573834e585 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/assign-pod-security-policies.html @@ -5,7 +5,7 @@ Assigning Pod Security Policies | Rancher Manager - + @@ -14,7 +14,7 @@ Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see Creating Pod Security Policies. Note: For security purposes, we recommend assigning a PSP as you create your clusters.

    To enable a default Pod Security Policy, set the Pod Security Policy Support option to Enabled, and then make a selection from the Default Pod Security Policy drop-down.

    When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html index 373ade7d2c3..287e056d41e 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clean-cluster-nodes.html @@ -5,13 +5,13 @@ Removing Kubernetes Components from Nodes | Rancher Manager - +
    Version: v2.5

    Removing Kubernetes Components from Nodes

    This section describes how to disconnect a node from a Rancher-launched Kubernetes cluster and remove all of the Kubernetes components from the node. This process allows you to use the node for other purposes.

    When you use Rancher to install Kubernetes on new nodes in an infrastructure provider, resources (containers/virtual network interfaces) and configuration items (certificates/configuration files) are created.

    When removing nodes from your Rancher launched Kubernetes cluster (provided that they are in Active state), those resources are automatically cleaned, and the only action needed is to restart the node. When a node has become unreachable and the automatic cleanup process cannot be used, we describe the steps that need to be executed before the node can be added to a cluster again.

    What Gets Removed?​

    When cleaning nodes provisioned using Rancher, the following components are deleted based on the type of cluster node you're removing.

    Removed ComponentNodes Hosted by Infrastructure ProviderCustom NodesHosted ClusterRegistered Nodes
    The Rancher deployment namespace (cattle-system by default)✓✓✓✓
    serviceAccount, clusterRoles, and clusterRoleBindings labeled by Rancher✓✓✓✓
    Labels, Annotations, and Finalizers✓✓✓✓
    Rancher Deployment✓✓✓
    Machines, clusters, projects, and user custom resource definitions (CRDs)✓✓✓
    All resources create under the management.cattle.io API Group✓✓✓
    All CRDs created by Rancher v2.x✓✓✓

    Removing a Node from a Cluster by Rancher UI​

    When the node is in Active state, removing the node from a cluster will trigger a process to clean up the node. Please restart the node after the automatic cleanup process is done to make sure any non-persistent data is properly removed.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    Removing Rancher Components from a Cluster Manually​

    When a node is unreachable and removed from the cluster, the automatic cleaning process can't be triggered because the node is unreachable. Please follow the steps below to manually remove the Rancher components.

    Warning: The commands listed below will remove data from the node. Make sure you have created a backup of files you want to keep before executing any of the commands as data will be lost.

    Removing Rancher Components from Registered Clusters​

    For registered clusters, the process for removing Rancher is a little different. You have the option of simply deleting the cluster in the Rancher UI, or your can run a script that removes Rancher components from the nodes. Both options make the same deletions.

    After the registered cluster is detached from Rancher, the cluster's workloads will be unaffected and you can access the cluster using the same methods that you did before the cluster was registered into Rancher.

    Warning: This process will remove data from your cluster. Make sure you have created a backup of files you want to keep before executing the command, as data will be lost.

    After you initiate the removal of a registered cluster using the Rancher UI (or API), the following events occur.

    1. Rancher creates a serviceAccount that it uses to remove the Rancher components from the cluster. This account is assigned the clusterRole and clusterRoleBinding permissions, which are required to remove the Rancher components.

    2. Using the serviceAccount, Rancher schedules and runs a job that cleans the Rancher components off of the cluster. This job also references the serviceAccount and its roles as dependencies, so the job deletes them before its completion.

    3. Rancher is removed from the cluster. However, the cluster persists, running the native version of Kubernetes.

    Result: All components listed for registered clusters in What Gets Removed? are deleted.

    Windows Nodes​

    To clean up a Windows node, you can run a cleanup script located in c:\etc\rancher. The script deletes Kubernetes generated resources and the execution binary. It also drops the firewall rules and network settings.

    To run the script, you can use this command in the PowerShell:

    pushd c:\etc\rancher
    .\cleanup.ps1
    popd

    Result: The node is reset and can be re-added to a Kubernetes cluster.

    Docker Containers, Images, and Volumes​

    Based on what role you assigned to the node, there are Kubernetes components in containers, containers belonging to overlay networking, DNS, ingress controller and Rancher agent. (and pods you created that have been scheduled to this node)

    To clean all Docker containers, images and volumes:

    docker rm -f $(docker ps -qa)
    docker rmi -f $(docker images -q)
    docker volume rm $(docker volume ls -q)

    Mounts​

    Kubernetes components and secrets leave behind mounts on the system that need to be unmounted.

    Mounts
    /var/lib/kubelet/pods/XXX (miscellaneous mounts)
    /var/lib/kubelet
    /var/lib/rancher

    To unmount all mounts:

    for mount in $(mount | grep tmpfs | grep '/var/lib/kubelet' | awk '{ print $3 }') /var/lib/kubelet /var/lib/rancher; do umount $mount; done

    Directories and Files​

    The following directories are used when adding a node to a cluster, and should be removed. You can remove a directory using rm -rf /directory_name.

    Note: Depending on the role you assigned to the node, some of the directories will or won't be present on the node.

    Directories
    /etc/ceph
    /etc/cni
    /etc/kubernetes
    /opt/cni
    /opt/rke
    /run/secrets/kubernetes.io
    /run/calico
    /run/flannel
    /var/lib/calico
    /var/lib/etcd
    /var/lib/cni
    /var/lib/kubelet
    /var/lib/rancher/rke/log
    /var/log/containers
    /var/log/kube-audit
    /var/log/pods
    /var/run/calico

    To clean the directories:

    rm -rf /etc/ceph \
           /etc/cni \
           /etc/kubernetes \
           /opt/cni \
           /opt/rke \
           /run/secrets/kubernetes.io \
           /run/calico \
           /run/flannel \
           /var/lib/calico \
           /var/lib/etcd \
           /var/lib/cni \
           /var/lib/kubelet \
           /var/lib/rancher/rke/log \
           /var/log/containers \
           /var/log/kube-audit \
           /var/log/pods \
           /var/run/calico

    Network Interfaces and Iptables​

    The remaining two components that are changed/configured are (virtual) network interfaces and iptables rules. Both are non-persistent to the node, meaning that they will be cleared after a restart of the node. To remove these components, a restart is recommended.

    To restart a node:

    # using reboot
    $ sudo reboot

    # using shutdown
    $ sudo shutdown -r now

    If you want to know more on (virtual) network interfaces or iptables rules, please see the specific subjects below.

    Network Interfaces​

    Note: Depending on the network provider configured for the cluster the node was part of, some of the interfaces will or won't be present on the node.

    Interfaces
    flannel.1
    cni0
    tunl0
    caliXXXXXXXXXXX (random interface names)
    vethXXXXXXXX (random interface names)

    To list all interfaces:

    # Using ip
    ip address show

    # Using ifconfig
    ifconfig -a

    To remove an interface:

    ip link delete interface_name

    Iptables​

    Note: Depending on the network provider configured for the cluster the node was part of, some of the chains will or won't be present on the node.

    Iptables rules are used to route traffic from and to containers. The created rules are not persistent, so restarting the node will restore iptables to its original state.

    Chains
    cali-failsafe-in
    cali-failsafe-out
    cali-fip-dnat
    cali-fip-snat
    cali-from-hep-forward
    cali-from-host-endpoint
    cali-from-wl-dispatch
    cali-fw-caliXXXXXXXXXXX (random chain names)
    cali-nat-outgoing
    cali-pri-kns.NAMESPACE (chain per namespace)
    cali-pro-kns.NAMESPACE (chain per namespace)
    cali-to-hep-forward
    cali-to-host-endpoint
    cali-to-wl-dispatch
    cali-tw-caliXXXXXXXXXXX (random chain names)
    cali-wl-to-host
    KUBE-EXTERNAL-SERVICES
    KUBE-FIREWALL
    KUBE-MARK-DROP
    KUBE-MARK-MASQ
    KUBE-NODEPORTS
    KUBE-SEP-XXXXXXXXXXXXXXXX (random chain names)
    KUBE-SERVICES
    KUBE-SVC-XXXXXXXXXXXXXXXX (random chain names)

    To list all iptables rules:

    iptables -L -t nat
    iptables -L -t mangle
    iptables -L
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html index ee1804f8b97..c1639cbd85f 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/clone-cluster-configuration.html @@ -5,13 +5,13 @@ Cloning Clusters | Rancher Manager - +
    Version: v2.5

    Cloning Clusters

    If you have a cluster in Rancher that you want to use as a template for creating similar clusters, you can use Rancher CLI to clone the cluster's configuration, edit it, and then use it to quickly launch the cloned cluster.

    Duplication of registered clusters is not supported.

    Cluster TypeCloneable?
    Nodes Hosted by Infrastructure Provider✓
    Hosted Kubernetes Providers✓
    Custom Cluster✓
    Registered Cluster

    Warning: During the process of duplicating a cluster, you will edit a config file full of cluster settings. However, we recommend editing only values explicitly listed in this document, as cluster duplication is designed for simple cluster copying, not wide scale configuration changes. Editing other values may invalidate the config file, which will lead to cluster deployment failure.

    Prerequisites​

    Download and install Rancher CLI. Remember to create an API bearer token if necessary.

    1. Export Cluster Config​

    Begin by using Rancher CLI to export the configuration for the cluster that you want to clone.

    1. Open Terminal and change your directory to the location of the Rancher CLI binary, rancher.

    2. Enter the following command to list the clusters managed by Rancher.

        ./rancher cluster ls

    1. Find the cluster that you want to clone, and copy either its resource ID or NAME to your clipboard. From this point on, we'll refer to the resource ID or NAME as <RESOURCE_ID>, which is used as a placeholder in the next step.

    2. Enter the following command to export the configuration for your cluster.

        ./rancher clusters export <RESOURCE_ID>


    **Step Result:** The YAML for a cloned cluster prints to Terminal.
    1. Copy the YAML to your clipboard and paste it in a new file. Save the file as cluster-template.yml (or any other name, as long as it has a .yml extension).

    2. Modify Cluster Config​

    Use your favorite text editor to modify the cluster configuration in cluster-template.yml for your cloned cluster.

    Note: Cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    1. Open cluster-template.yml (or whatever you named your config) in your favorite text editor.

      Warning: Only edit the cluster config values explicitly called out below. Many of the values listed in this file are used to provision your cloned cluster, and editing their values may break the provisioning process.

    1. As depicted in the example below, at the <CLUSTER_NAME> placeholder, replace your original cluster's name with a unique name (<CLUSTER_NAME>). If your cloned cluster has a duplicate name, the cluster will not provision successfully.

      Version: v3
      clusters:
          <CLUSTER_NAME>: # ENTER UNIQUE NAME
          dockerRootDir: /var/lib/docker
          enableNetworkPolicy: false
          rancherKubernetesEngineConfig:
          addonJobTimeout: 30
          authentication:
              strategy: x509
          authorization: {}
          bastionHost: {}
          cloudProvider: {}
          ignoreDockerVersion: true

    2. For each nodePools section, replace the original nodepool name with a unique name at the <NODEPOOL_NAME> placeholder. If your cloned cluster has a duplicate nodepool name, the cluster will not provision successfully.

      nodePools:
          <NODEPOOL_NAME>:
          clusterId: do
          controlPlane: true
          etcd: true
          hostnamePrefix: mark-do
          nodeTemplateId: do
          quantity: 1
          worker: true

    3. When you're done, save and close the configuration.

    3. Launch Cloned Cluster​

    Move cluster-template.yml into the same directory as the Rancher CLI binary. Then run this command:

    ./rancher up --file cluster-template.yml

    Result: Your cloned cluster begins provisioning. Enter ./rancher cluster ls to confirm. You can also log into the Rancher UI and open the Global view to watch your provisioning cluster's progress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html index f93ab302775..687184c0e4d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-glusterfs-volumes.html @@ -5,13 +5,13 @@ GlusterFS Volumes | Rancher Manager - +
    Version: v2.5

    GlusterFS Volumes

    This section only applies to RKE clusters.

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. The logging of the kubelet will show: transport endpoint is not connected. To prevent this from happening, you can configure your cluster to mount the systemd-run binary in the kubelet container. There are two requirements before you can change the cluster configuration:

    • The node needs to have the systemd-run binary installed (this can be checked by using the command which systemd-run on each cluster node)
    • The systemd-run binary needs to be compatible with Debian OS on which the hyperkube image is based (this can be checked using the following command on each cluster node, replacing the image tag with the Kubernetes version you want to use)
    docker run -v /usr/bin/systemd-run:/usr/bin/systemd-run --entrypoint /usr/bin/systemd-run rancher/hyperkube:v1.16.2-rancher1 --version

    Note:

    Before updating your Kubernetes YAML to mount the systemd-run binary, make sure the systemd package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.

    services:
      kubelet:
        extra_binds:
          - "/usr/bin/systemd-run:/usr/bin/systemd-run"

    After the cluster has finished provisioning, you can check the kubelet container logging to see if the functionality is activated by looking for the following logline:

    Detected OS with systemd
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html index 9b3099be905..62669800889 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/about-persistent-storage.html @@ -5,13 +5,13 @@ How Persistent Storage Works | Rancher Manager - +
    Version: v2.5

    How Persistent Storage Works

    A persistent volume (PV) is a piece of storage in the Kubernetes cluster, while a persistent volume claim (PVC) is a request for storage.

    There are two ways to use persistent storage in Kubernetes:

    • Use an existing persistent volume
    • Dynamically provision new persistent volumes

    To use an existing PV, your application will need to use a PVC that is bound to a PV, and the PV should include the minimum resources that the PVC requires.

    For dynamic storage provisioning, your application will need to use a PVC that is bound to a storage class. The storage class contains the authorization to provision new persistent volumes.

    Setting Up New and Existing Persistent Storage

    For more information, refer to the official Kubernetes documentation on storage

    About Persistent Volume Claims​

    Persistent volume claims (PVCs) are objects that request storage resources from your cluster. They're similar to a voucher that your deployment can redeem for storage access. A PVC is mounted into a workloads as a volume so that the workload can claim its specified share of the persistent storage.

    To access persistent storage, a pod must have a PVC mounted as a volume. This PVC lets your deployment application store its data in an external location, so that if a pod fails, it can be replaced with a new pod and continue accessing its data stored externally, as though an outage never occurred.

    Each Rancher project contains a list of PVCs that you've created, available from Resources > Workloads > Volumes. You can reuse these PVCs when creating deployments in the future.

    PVCs are Required for Both New and Existing Persistent Storage​

    A PVC is required for pods to use any persistent storage, regardless of whether the workload is intended to use storage that already exists, or the workload will need to dynamically provision new storage on demand.

    If you are setting up existing storage for a workload, the workload mounts a PVC, which refers to a PV, which corresponds to existing storage infrastructure.

    If a workload should request new storage, the workload mounts PVC, which refers to a storage class, which has the capability to create a new PV along with its underlying storage infrastructure.

    Rancher lets you create as many PVCs within a project as you'd like.

    You can mount PVCs to a deployment as you create it, or later, after the deployment is running.

    Setting up Existing Storage with a PVC and PV​

    Your pods can store data in volumes, but if the pod fails, that data is lost. To solve this issue, Kubernetes offers persistent volumes (PVs), which are Kubernetes resources that correspond to external storage disks or file systems that your pods can access. If a pod crashes, its replacement pod can access the data in persistent storage without any data loss.

    PVs can represent a physical disk or file system that you host on premise, or a vendor-hosted storage resource, such as Amazon EBS or Azure Disk.

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    Important: PVs are created at the cluster level, which means that in a multi-tenant cluster, teams with access to separate namespaces could have access to the same PV.

    Binding PVs to PVCs​

    When pods are set up to use persistent storage, they mount a persistent volume claim (PVC) that is mounted the same way as any other Kubernetes volume. When each PVC is created, the Kubernetes master considers it to be a request for storage and binds it to a PV that matches the minimum resource requirements of the PVC. Not every PVC is guaranteed to be bound to a PV. According to the Kubernetes documentation,

    Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.

    In other words, you can create unlimited PVCs, but they will only be bound to PVs if the Kubernetes master can find a sufficient PVs that has at least the amount of disk space required by the PVC.

    To dynamically provision new storage, the PVC mounted in the pod would have to correspond to a storage class instead of a persistent volume.

    Provisioning New Storage with a PVC and Storage Class​

    Storage Classes allow you to create PVs dynamically without having to create persistent storage in an infrastructure provider first.

    For example, if a workload is bound to a PVC and the PVC refers to an Amazon EBS Storage Class, the storage class can dynamically create an EBS volume and a corresponding PV.

    The Kubernetes master will then bind the newly created PV to your workload's PVC, allowing your workload to use the persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html index 45b90b9e975..3207a4b25db 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/dynamically-provision-new-storage.html @@ -5,13 +5,13 @@ Dynamically Provisioning New Storage in Rancher | Rancher Manager - +
    Version: v2.5

    Dynamically Provisioning New Storage in Rancher

    This section describes how to provision new persistent storage for workloads in Rancher.

    This section assumes that you understand the Kubernetes concepts of storage classes and persistent volume claims. For more information, refer to the section on how storage works.

    New storage is often provisioned by a cloud provider such as Amazon EBS. However, new storage doesn't have to be in the cloud.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see this page.

    To provision new storage for your workloads, follow these steps:

    1. Add a storage class and configure it to use your storage.
    2. Add a persistent volume claim that refers to the storage class.
    3. Mount the persistent volume claim as a volume for your workload.

    Prerequisites​

    • To set up persistent storage, the Manage Volumes role is required.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.
    • The cloud provider must be enabled. For details on enabling cloud providers, refer to this page.
    • Make sure your storage provisioner is available to be enabled.

    The following storage provisioners are enabled by default:

    NamePlugin
    Amazon EBS Diskaws-ebs
    AzureFileazure-file
    AzureDiskazure-disk
    Google Persistent Diskgce-pd
    Longhornflex-volume-longhorn
    VMware vSphere Volumevsphere-volume
    Locallocal
    Network File Systemnfs
    hostPathhost-path

    To use a storage provisioner that is not on the above list, you will need to use a feature flag to enable unsupported storage drivers.

    1. Add a storage class and configure it to use your storage​

    These steps describe how to set up a storage class at the cluster level.

    1. Go to the Cluster Explorer of the cluster for which you want to dynamically provision persistent storage volumes.

    2. From the cluster view, select Storage > Storage Classes. Click Add Class.

    3. Enter a Name for your storage class.

    4. From the Provisioner drop-down, select the service that you want to use to dynamically provision storage volumes. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, use the Amazon EBS Disk provisioner.

    5. From the Parameters section, fill out the information required for the service to dynamically provision storage volumes. Each provisioner requires different information to dynamically provision storage volumes. Consult the service's documentation for help on how to obtain this information.

    6. Click Save.

    Result: The storage class is available to be consumed by a PVC.

    For full information about the storage class parameters, refer to the official Kubernetes documentation..

    2. Add a persistent volume claim that refers to the storage class​

    These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.

    1. Go to the Cluster Manager to the project containing a workload that you want to add a PVC to.

    2. From the main navigation bar, choose Resources > Workloads. Then select the Volumes tab. Click Add Volume.

    3. Enter a Name for the volume claim.

    4. Select the namespace of the volume claim.

    5. In the Source field, click Use a Storage Class to provision a new persistent volume.

    6. Go to the Storage Class drop-down and select the storage class that you created.

    7. Enter a volume Capacity.

    8. Optional: Expand the Customize section and select the Access Modes that you want to use.

    9. Click Create.

    Result: Your PVC is created. You can now attach it to any workload in the project.

    3. Mount the persistent volume claim as a volume for your workload​

    Mount PVCs to workloads so that your applications can store their data.

    You can mount PVCs during the deployment of a workload, or following workload creation.

    To attach the PVC to a new workload,

    1. Create a workload as you would in Deploying Workloads.
    2. For Workload Type, select Stateful set of 1 pod.
    3. Expand the Volumes section and click Add Volume > Add a New Persistent Volume (Claim).
    4. In the Persistent Volume Claim section, select the newly created persistent volume claim that is attached to the storage class.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Launch.

    Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    To attach the PVC to an existing workload,

    1. Go to the project that has the workload that will have the PVC attached.
    2. Go to the workload that will have persistent storage and click ⋮ > Edit.
    3. Expand the Volumes section and click Add Volume > Add a New Persistent Volume (Claim).
    4. In the Persistent Volume Claim section, select the newly created persistent volume claim that is attached to the storage class.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Save.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC. If not, Rancher will provision new persistent storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html index 626c1a53f2c..294aa880ca6 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/install-iscsi-volumes.html @@ -5,13 +5,13 @@ iSCSI Volumes | Rancher Manager - +
    Version: v2.5

    iSCSI Volumes

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. This failure is likely due to an incompatibility issue involving the iSCSI initiator tool. You can resolve this issue by installing the iSCSI initiator tool on each of your cluster nodes.

    Rancher Launched Kubernetes clusters storing data on iSCSI volumes leverage the iSCSI initiator tool, which is embedded in the kubelet's rancher/hyperkube Docker image. From each kubelet (i.e., the initiator), the tool discovers and launches sessions with an iSCSI volume (i.e., the target). However, in some instances, the versions of the iSCSI initiator tool installed on the initiator and the target may not match, resulting in a connection failure.

    If you encounter this issue, you can work around it by installing the initiator tool on each node in your cluster. You can install the iSCSI initiator tool by logging into your cluster nodes and entering one of the following commands:

    PlatformPackage NameInstall Command
    Ubuntu/Debianopen-iscsisudo apt install open-iscsi
    RHELiscsi-initiator-utilsyum install iscsi-initiator-utils -y

    After installing the initiator tool on your nodes, edit the YAML for your cluster, editing the kubelet configuration to mount the iSCSI binary and configuration, as shown in the sample below.

    Notes:

    • Before updating your Kubernetes YAML to mount the iSCSI binary and configuration, make sure either the open-iscsi (deb) or iscsi-initiator-utils (yum) package is installed on your cluster nodes. If this package isn't installed before the bind mounts are created in your Kubernetes YAML, Docker will automatically create the directories and files on each node and will not allow the package install to succeed.


    • The example YAML below does not apply to K3s, but only to RKE clusters. Since the K3s kubelet does not run in a container, adding extra binds is not necessary. However, all iSCSI tools must still be installed on your K3s nodes.

    services:
      kubelet:
        extra_binds:
          - "/etc/iscsi:/etc/iscsi"
          - "/sbin/iscsiadm:/sbin/iscsiadm"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html index 53eb6f4a351..142c0102aff 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/set-up-existing-storage.html @@ -5,13 +5,13 @@ Setting up Existing Storage | Rancher Manager - +
    Version: v2.5

    Setting up Existing Storage

    This section describes how to set up existing persistent storage for workloads in Rancher.

    This section assumes that you understand the Kubernetes concepts of persistent volumes and persistent volume claims. For more information, refer to the section on how storage works.

    To set up storage, follow these steps:

    1. Set up persistent storage.
    2. Add a persistent volume that refers to the persistent storage.
    3. Add a persistent volume claim that refers to the persistent volume.
    4. Mount the persistent volume claim as a volume in your workload.

    Prerequisites​

    • To create a persistent volume as a Kubernetes resource, you must have the Manage Volumes role.
    • If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    1. Set up persistent storage​

    Creating a persistent volume in Rancher will not create a storage volume. It only creates a Kubernetes resource that maps to an existing volume. Therefore, before you can create a persistent volume as a Kubernetes resource, you must have storage provisioned.

    The steps to set up a persistent storage device will differ based on your infrastructure. We provide examples of how to set up storage using vSphere, NFS, or Amazon's EBS.

    If you have a pool of block storage, and you don't want to use a cloud provider, Longhorn could help you provide persistent storage to your Kubernetes cluster. For more information, see this page.

    2. Add a persistent volume that refers to the persistent storage​

    These steps describe how to set up a persistent volume at the cluster level in Kubernetes.

    1. From the cluster view, select Storage > Persistent Volumes.

    2. Click Add Volume.

    3. Enter a Name for the persistent volume.

    4. Select the Volume Plugin for the disk type or service that you're using. When adding storage to a cluster that's hosted by a cloud provider, use the cloud provider's plug-in for cloud storage. For example, if you have a Amazon EC2 cluster and you want to use cloud storage for it, you must use the Amazon EBS Disk volume plugin.

    5. Enter the Capacity of your volume in gigabytes.

    6. Complete the Plugin Configuration form. Each plugin type requires information specific to the vendor of disk type. For help regarding each plugin's form and the information that's required, refer to the plug-in's vendor documentation.

    7. Optional: In the Customize form, configure the access modes. This options sets how many nodes can access the volume, along with the node read/write permissions. The Kubernetes Documentation includes a table that lists which access modes are supported by the plugins available.

    8. Optional: In the Customize form, configure the mount options. Each volume plugin allows you to specify additional command line options during the mounting process. Consult each plugin's vendor documentation for the mount options available.

    9. Click Save.

    Result: Your new persistent volume is created.

    3. Add a persistent volume claim that refers to the persistent volume​

    These steps describe how to set up a PVC in the namespace where your stateful workload will be deployed.

    1. Go to the project containing a workload that you want to add a persistent volume claim to.

    2. Then click the Volumes tab and click Add Volume.

    3. Enter a Name for the volume claim.

    4. Select the namespace of the workload that you want to add the persistent storage to.

    5. In the section called Use an existing persistent volume, go to the Persistent Volume drop-down and choose the persistent volume that you created.

    6. Optional: From Customize, select the Access Modes that you want to use.

    7. Click Create.

    Result: Your PVC is created. You can now attach it to any workload in the project.

    4. Mount the persistent volume claim as a volume in your workload​

    Mount PVCs to stateful workloads so that your applications can store their data.

    You can mount PVCs during the deployment of a workload, or following workload creation.

    The following steps describe how to assign existing storage to a new workload that is a stateful set:

    1. From the Project view, go to the Workloads tab.
    2. Click Deploy.
    3. Enter a name for the workload.
    4. Next to the Workload Type field, click More Options.
    5. Click Stateful set of 1 pod. Optionally, configure the number of pods.
    6. Choose the namespace where the workload will be deployed.
    7. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
    8. In the Persistent Volume Claim field, select the PVC that you created.
    9. In the Mount Point field, enter the path that the workload will use to access the volume.
    10. Click Launch.

    Result: When the workload is deployed, it will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    The following steps describe how to assign persistent storage to an existing workload:

    1. From the Project view, go to the Workloads tab.
    2. Go to the workload that you want to add the persistent storage to. The workload type should be a stateful set. Click ⋮ > Edit.
    3. Expand the Volumes section and click Add Volume > Use an existing persistent volume (claim)..
    4. In the Persistent Volume Claim field, select the PVC that you created.
    5. In the Mount Point field, enter the path that the workload will use to access the volume.
    6. Click Save.

    Result: The workload will make a request for the specified amount of disk space to the Kubernetes master. If a PV with the specified resources is available when the workload is deployed, the Kubernetes master will bind the PV to the PVC.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html index abb678b23cb..fed503ff29b 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/manage-persistent-storage/use-external-ceph-driver.html @@ -5,13 +5,13 @@ Using an External Ceph Driver | Rancher Manager - +
    Version: v2.5

    Using an External Ceph Driver

    These instructions are about using the external Ceph driver in an RKE2 cluster. If you are using RKE, additional steps are required. For details, refer to this section.

    Requirements​

    Make sure ceph-common and xfsprogs packages are installed on SLE worker nodes.

    Using the Ceph Driver with RKE​

    The resources below are fully compatible with RKE based clusters, but there is a need to do an additional kubelet configuration for RKE.

    On RKE clusters, the kubelet component is running in a Docker container and doesn't have access to the host's kernel modules as rbd and libceph by default.

    To solve this limitation, you can either run modprobe rbd on worker nodes, or configure the kubelet containers to automatically mount the /lib/modules directory from the host into the container.

    For the kubelet configuration, put the following lines into the cluster.yml file prior to RKE cluster provisioning. You can also modify the cluster.yml later in the Rancher UI by clicking on Edit Cluster > Edit as YAML and restarting the worker nodes.

    services:
      kubelet:
        extra_binds:
          - '/lib/modules:/lib/modules:ro'

    For more information about the extra_binds directive, refer to this section.

    Installing the ceph-csi driver on an RKE2 cluster​

    Note: These steps are needed for dynamic RBD provisioning only.

    For more information about the ceph-csi-rbd chart, refer to this page.

    To get details about your SES cluster, run:

    ceph mon dump

    Read its output:

    dumped monmap epoch 3
    epoch 3
    fsid 79179d9d-98d8-4976-ab2e-58635caa7235
    last_changed 2021-02-11T10:56:42.110184+0000
    created 2021-02-11T10:56:22.913321+0000
    min_mon_release 15 (octopus)
    0: [v2:10.85.8.118:3300/0,v1:10.85.8.118:6789/0] mon.a
    1: [v2:10.85.8.123:3300/0,v1:10.85.8.123:6789/0] mon.b
    2: [v2:10.85.8.124:3300/0,v1:10.85.8.124:6789/0] mon.c

    Later you'll need the fsid and mon addresses values.

    Install the ceph-csi Driver Using Helm​

    Run these commands:

    helm repo add ceph-csi https://ceph.github.io/csi-charts
    helm repo update
    helm search repo ceph-csi -l
    helm inspect values ceph-csi/ceph-csi-rbd > ceph-csi-rbd-values.yaml

    Modify the ceph-csi-rbd-values.yaml file and keep there only the required changes:

    # ceph-csi-rbd-values.yaml
    csiConfig:
      - clusterID: "79179d9d-98d8-4976-ab2e-58635caa7235"
        monitors:
          - "10.85.8.118:6789"
          - "10.85.8.123:6789"
          - "10.85.8.124:6789"
    provisioner:
      name: provisioner
      replicaCount: 2

    Make sure the ceph monitors are reachable from the RKE2 cluster, for example, by ping.

    kubectl create namespace ceph-csi-rbd
    helm install --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml
    kubectl rollout status deployment ceph-csi-rbd-provisioner -n ceph-csi-rbd
    helm status ceph-csi-rbd -n ceph-csi-rbd

    in case you'd like to modify the configuration directly via Helm, you may adapt the ceph-csi-rbd-values.yaml file and call:

    helm upgrade \
      --namespace ceph-csi-rbd ceph-csi-rbd ceph-csi/ceph-csi-rbd --values ceph-csi-rbd-values.yaml

    Creating RBD Ceph Resources​

    # Create a ceph pool:
    ceph osd pool create myPool 64 64

    # Create a block device pool:
    rbd pool init myPool

    # Create a block device image:
    rbd create -s 2G myPool/image

    # Create a block device user and record the key:
    ceph auth get-or-create-key client.myPoolUser mon "allow r" osd "allow class-read object_prefix rbd_children, allow rwx pool=myPool" | tr -d '\n' | base64
    QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ==

    # Encode the ceph user myPoolUser into a bash64 hash:
    echo "myPoolUser" | tr -d '\n' | base64
    bXlQb29sVXNlcg==

    # Create a block device admin user and record the key:
    ceph auth get-or-create-key client.myPoolAdmin mds 'allow *' mgr 'allow *' mon 'allow *' osd 'allow * pool=myPool' | tr -d '\n' | base64
    QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ==

    # Encode the ceph user myPoolAdmin into a bash64 hash:
    echo "myPoolAdmin" | tr -d '\n' | base64
    bXlQb29sQWRtaW4=

    Configure RBD Ceph Access Secrets​

    User Account​

    For static RBD provisioning (the image within the ceph pool must exist), run these commands:

    cat > ceph-user-secret.yaml << EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: ceph-user
      namespace: default
    type: kubernetes.io/rbd
    data:
      userID: bXlQb29sVXNlcg==
      userKey: QVFDZ0R5VmdyRk9KREJBQTJ5b2s5R1E2NUdSWExRQndhVVBwWXc9PQ==
    EOF

    kubectl apply -f ceph-user-secret.yaml

    Admin Account​

    For dynamic RBD provisioning (used for automatic image creation within a given ceph pool), run these commands:

    cat > ceph-admin-secret.yaml << EOF
    apiVersion: v1
    kind: Secret
    metadata:
      name: ceph-admin
      namespace: default
    type: kubernetes.io/rbd
    data:
      userID: bXlQb29sQWRtaW4=
      userKey: QVFCK0hDVmdXSjQ1T0JBQXBrc0VtcVhlZFpjc0JwaStIcmU5M3c9PQ==
    EOF

    kubectl apply -f ceph-admin-secret.yaml

    Create RBD Testing Resources​

    Using RBD in Pods​

    # pod
    cat > ceph-rbd-pod-inline.yaml << EOF
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-inline
    spec:
      containers:
      - name: ceph-rbd-pod-inline
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        rbd:
          monitors:
          - 10.85.8.118:6789
          - 10.85.8.123:6789
          - 10.85.8.124:6789
          pool: myPool
          image: image
          user: myPoolUser
          secretRef:
            name: ceph-user
          fsType: ext4
          readOnly: false
    EOF

    kubectl apply -f ceph-rbd-pod-inline.yaml
    kubectl get pod
    kubectl exec pod/ceph-rbd-pod-inline -- df -k | grep rbd

    Using RBD in Persistent Volumes​

    # pod-pvc-pv
    cat > ceph-rbd-pod-pvc-pv-allinone.yaml << EOF
    apiVersion: v1
    kind: PersistentVolume
    metadata:
      name: ceph-rbd-pv
    spec:
      capacity:
        storage: 2Gi
      accessModes:
        - ReadWriteOnce
      rbd:
        monitors:
        - 10.85.8.118:6789
        - 10.85.8.123:6789
        - 10.85.8.124:6789
        pool: myPool
        image: image
        user: myPoolUser
        secretRef:
          name: ceph-user
        fsType: ext4
        readOnly: false
    ---
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: ceph-rbd-pvc
    spec:
      accessModes:
      - ReadWriteOnce
      resources:
        requests:
          storage: 2Gi
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-pvc-pv
    spec:
      containers:
      - name: ceph-rbd-pod-pvc-pv
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        persistentVolumeClaim:
          claimName: ceph-rbd-pvc
    EOF

    kubectl apply -f ceph-rbd-pod-pvc-pv-allinone.yaml
    kubectl get pv,pvc,pod
    kubectl exec pod/ceph-rbd-pod-pvc-pv -- df -k | grep rbd

    Using RBD in Storage Classes​

    This example is for dynamic provisioning. The ceph-csi driver is needed.

    # pod-pvc-sc
    cat > ceph-rbd-pod-pvc-sc-allinone.yaml <<EOF
    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: ceph-rbd-sc
      annotations:
        storageclass.kubernetes.io/is-default-class: "true"
    provisioner: rbd.csi.ceph.com
    parameters:
       clusterID: 79179d9d-98d8-4976-ab2e-58635caa7235
       pool: myPool
       imageFeatures: layering
       csi.storage.k8s.io/provisioner-secret-name: ceph-admin
       csi.storage.k8s.io/provisioner-secret-namespace: default
       csi.storage.k8s.io/controller-expand-secret-name: ceph-admin
       csi.storage.k8s.io/controller-expand-secret-namespace: default
       csi.storage.k8s.io/node-stage-secret-name: ceph-admin
       csi.storage.k8s.io/node-stage-secret-namespace: default
    reclaimPolicy: Delete
    allowVolumeExpansion: true
    mountOptions:
       - discard
    ---
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: ceph-rbd-sc-pvc
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 2Gi
      storageClassName: ceph-rbd-sc
    ---
    apiVersion: v1
    kind: Pod
    metadata:
      name: ceph-rbd-pod-pvc-sc
    spec:
      containers:
      - name:  ceph-rbd-pod-pvc-sc
        image: busybox
        command: ["sleep", "infinity"]
        volumeMounts:
        - mountPath: /mnt/ceph_rbd
          name: volume
      volumes:
      - name: volume
        persistentVolumeClaim:
          claimName: ceph-rbd-sc-pvc
    EOF

    kubectl apply -f ceph-rbd-pod-pvc-sc-allinone.yaml
    kubectl get pv,pvc,sc,pod
    kubectl exec pod/ceph-rbd-pod-pvc-sc -- df -k | grep rbd

    RKE2 Server/Master Provisioning​

    sudo su
    curl -sfL https://get.rke2.io | sh -
    systemctl enable --now rke2-server

    cat > /root/.bashrc << EOF
    export PATH=$PATH:/var/lib/rancher/rke2/bin/
    export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
    EOF

    cat /var/lib/rancher/rke2/server/node-token
    token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED

    RKE2 Agent/Worker provisioning​

    mkdir -p /etc/rancher/rke2/

    cat > /etc/rancher/rke2/config.yaml << EOF
    server: https://10.100.103.23:9345
    token: K10ca0c38d4ff90d8b80319ab34092e315a8b732622e6adf97bc9eb0536REDACTED::server:ec0308000b8a6b595da000efREDACTED
    EOF

    curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -
    systemctl enable --now rke2-agent.service

    The cluster can be imported into Rancher from the Rancher UI by clicking Global/Add Cluster > Other Cluster. Then run the provided kubectl command on the server/master node.

    Tested Versions​

    OS for running RKE2 nodes: JeOS SLE15-SP2 with installed kernel-default-5.3.18-24.49

    kubectl version
    Client Version: version.Info{Major:"1", Minor:"18", GitVersion:"v1.18.4", GitCommit:"c96aede7b5205121079932896c4ad89bb93260af", GitTreeState:"clean", BuildDate:"2020-06-22T12:00:00Z", GoVersion:"go1.13.11", Compiler:"gc", Platform:"linux/amd64"}
    Server Version: version.Info{Major:"1", Minor:"19", GitVersion:"v1.19.7+rke2r1", GitCommit:"1dd5338295409edcfff11505e7bb246f0d325d15", GitTreeState:"clean", BuildDate:"2021-01-20T01:50:52Z", GoVersion:"go1.15.5b5", Compiler:"gc", Platform:"linux/amd64"}

    helm version
    version.BuildInfo{Version:"3.4.1", GitCommit:"c4e74854886b2efe3321e185578e6db9be0a6e29", GitTreeState:"clean", GoVersion:"go1.14.12"}

    Kubernetes version on RKE2 cluster: v1.19.7+rke2r1

    Troubleshooting​

    In case you are using SUSE's ceph-rook based on SES7, it might be useful to expose the monitors on hostNetwork by editing rook-1.4.5/ceph/cluster.yaml and setting spec.network.hostNetwork=true.

    Also for operating the ceph-rook cluster, it is useful to deploy a toolbox on the Kubernetes cluster where ceph-rook is provisioned by kubectl apply -f rook-1.4.5/ceph/toolbox.yaml Then all the ceph related commands can be executed in the toolbox pod, for example, by running kubectl exec -it -n rook-ceph rook-ceph-tools-686d8b8bfb-2nvqp -- bash

    Operating with the ceph - basic commands:

    ceph osd pool stats
    ceph osd pool delete myPool myPool --yes-i-really-really-mean-it
    rbd list -p myPool
    > csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38
    > image

    Delete the image: rbd rm csi-vol-f5d3766c-7296-11eb-b32a-c2b045952d38 -p myPool

    CephFS commands in rook toolbox:

    ceph -s
    ceph fs ls
    ceph fs fail cephfs
    ceph fs rm cephfs --yes-i-really-mean-it
    ceph osd pool delete cephfs_data cephfs_data --yes-i-really-really-mean-it
    ceph osd pool delete cephfs_metadata cephfs_metadata --yes-i-really-really-mean-it

    To prepare a cephfs filesystem, you can run this command on a rook cluster:

    kubectl apply -f rook-1.4.5/ceph/filesystem.yaml
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html index a5118bbe2a6..d36b1975155 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/nfs-storage.html @@ -5,13 +5,13 @@ NFS Storage | Rancher Manager - +
    Version: v2.5

    NFS Storage

    Before you can use the NFS storage volume plug-in with Rancher deployments, you need to provision an NFS server.

    Note:

    • If you already have an NFS share, you don't need to provision a new NFS server to use the NFS volume plugin within Rancher. Instead, skip the rest of this procedure and complete adding storage.

    • This procedure demonstrates how to set up an NFS server using Ubuntu, although you should be able to use these instructions for other Linux distros (e.g. Debian, RHEL, Arch Linux, etc.). For official instruction on how to create an NFS server using another Linux distro, consult the distro's documentation.

    Recommended: To simplify the process of managing firewall rules, use NFSv4.

    1. Using a remote Terminal connection, log into the Ubuntu server that you intend to use for NFS storage.

    2. Enter the following command:

      sudo apt-get install nfs-kernel-server

    3. Enter the command below, which sets the directory used for storage, along with user access rights. Modify the command if you'd like to keep storage at a different directory.

      mkdir -p /nfs && chown nobody:nogroup /nfs
      • The -p /nfs parameter creates a directory named nfs at root.
      • The chown nobody:nogroup /nfs parameter allows all access to the storage directory.

    4. Create an NFS exports table. This table sets the directory paths on your NFS server that are exposed to the nodes that will use the server for storage.

      1. Open /etc/exports using your text editor of choice.

      2. Add the path of the /nfs folder that you created in step 3, along with the IP addresses of your cluster nodes. Add an entry for each IP address in your cluster. Follow each address and its accompanying parameters with a single space that is a delimiter.

        /nfs <IP_ADDRESS1>(rw,sync,no_subtree_check) <IP_ADDRESS2>(rw,sync,no_subtree_check) <IP_ADDRESS3>(rw,sync,no_subtree_check)

        Tip: You can replace the IP addresses with a subnet. For example: 10.212.50.12&#47;24

      3. Update the NFS table by entering the following command:

        exportfs -ra

    5. Open the ports used by NFS.

      1. To find out what ports NFS is using, enter the following command:

        rpcinfo -p | grep nfs

      2. Open the ports that the previous command outputs. For example, the following command opens port 2049:

        sudo ufw allow 2049

    Result: Your NFS server is configured to be used for storage with your Rancher nodes.

    What's Next?​

    Within Rancher, add the NFS server as a storage volume and/or storage class. After adding the server, you can use it for storage for your deployments.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html index f3623d54bc2..8c7dd4bb073 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/persistent-storage-in-amazon-ebs.html @@ -5,13 +5,13 @@ Creating Persistent Storage in Amazon's EBS | Rancher Manager - +
    Version: v2.5

    Creating Persistent Storage in Amazon's EBS

    This section describes how to set up Amazon's Elastic Block Store in EC2.

    1. From the EC2 console, go to the ELASTIC BLOCK STORE section in the left panel and click Volumes.
    2. Click Create Volume.
    3. Optional: Configure the size of the volume or other options. The volume should be created in the same availability zone as the instance it will be attached to.
    4. Click Create Volume.
    5. Click Close.

    Result: Persistent storage has been created.

    For details on how to set up the newly created storage in Rancher, refer to the section on setting up existing storage.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html index 0913e9de8ab..55adbc29cfc 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/create-kubernetes-persistent-storage/provisioning-storage-examples/vsphere-storage.html @@ -5,13 +5,13 @@ vSphere Storage | Rancher Manager - +
    Version: v2.5

    vSphere Storage

    To provide stateful workloads with vSphere storage, we recommend creating a vSphereVolume StorageClass. This practice dynamically provisions vSphere storage when workloads request volumes through a persistent volume claim.

    In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

    Prerequisites​

    In order to provision vSphere volumes in a cluster created with the Rancher Kubernetes Engine (RKE), the vSphere cloud provider must be explicitly enabled in the cluster options.

    Creating a StorageClass​

    Note:

    The following steps can also be performed using the kubectl command line tool. See Kubernetes documentation on persistent volumes for details.

    1. From the Global view, open the cluster where you want to provide vSphere storage.

    2. From the main menu, select Storage > Storage Classes. Then click Add Class.

    3. Enter a Name for the class.

    4. Under Provisioner, select VMWare vSphere Volume.

    5. Optionally, specify additional properties for this storage class under Parameters. Refer to the vSphere storage documentation for details.

    6. Click Save.

    Creating a Workload with a vSphere Volume​

    1. From the cluster where you configured vSphere storage, begin creating a workload as you would in Deploying Workloads.

    2. For Workload Type, select Stateful set of 1 pod.

    3. Expand the Volumes section and click Add Volume.

    4. Choose Add a new persistent volume (claim). This option will implicitly create the claim once you deploy the workload.

    5. Assign a Name for the claim, ie. test-volume and select the vSphere storage class created in the previous step.

    6. Enter the required Capacity for the volume. Then click Define.

    7. Assign a path in the Mount Point field. This is the full path where the volume will be mounted in the container file system, e.g. /persistent.

    8. Click Launch to create the workload.

    Verifying Persistence of the Volume​

    1. From the context menu of the workload you just created, click Execute Shell.

    2. Note the directory at root where the volume has been mounted to (in this case /persistent).

    3. Create a file in the volume by executing the command touch /<volumeMountPoint>/data.txt.

    4. Close the shell window.

    5. Click on the name of the workload to reveal detail information.

    6. Open the context menu next to the Pod in the Running state.

    7. Delete the Pod by selecting Delete.

    8. Observe that the pod is deleted. Then a new pod is scheduled to replace it so that the workload maintains its configured scale of a single stateful pod.

    9. Once the replacement pod is running, click Execute Shell.

    10. Inspect the contents of the directory where the volume is mounted by entering ls -l /<volumeMountPoint>. Note that the file you created earlier is still present.

      workload-persistent-data

    Why to Use StatefulSets Instead of Deployments​

    You should always use StatefulSets for workloads consuming vSphere storage, as this resource type is designed to address a VMDK block storage caveat.

    Since vSphere volumes are backed by VMDK block storage, they only support an access mode of ReadWriteOnce. This setting restricts the volume so that it can only be mounted to a single pod at a time, unless all pods consuming that volume are co-located on the same node. This behavior makes a deployment resource unusable for scaling beyond a single replica if it consumes vSphere volumes.

    Even using a deployment resource with just a single replica may result in a deadlock situation while updating the deployment. If the updated pod is scheduled to a node different from where the existing pod lives, it will fail to start because the VMDK is still attached to the other node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html index 9cb86241727..6e6170092f0 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/install-cluster-autoscaler/use-aws-ec2-auto-scaling-groups.html @@ -5,7 +5,7 @@ Cluster Autoscaler with AWS EC2 Auto Scaling Groups | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Cluster Autoscaler with AWS EC2 Auto Scaling Groups

    This guide will show you how to install and use Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

    We are going to install a Rancher RKE custom cluster with a fixed number of nodes with the etcd and controlplane roles, and a variable nodes with the worker role, managed by cluster-autoscaler.

    Prerequisites​

    These elements are required to follow this guide:

    • The Rancher server is up and running
    • You have an AWS EC2 user with proper permissions to create virtual machines, auto scaling groups, and IAM profiles and roles

    1. Create a Custom Cluster​

    On Rancher server, we should create a custom k8s cluster. Refer here to check for version compatibility.

    Be sure that cloud_provider name is set to amazonec2. Once cluster is created we need to get:

    • clusterID: c-xxxxx will be used on EC2 kubernetes.io/cluster/<clusterID> instance tag

    • clusterName: will be used on EC2 k8s.io/cluster-autoscaler/<clusterName> instance tag

    • nodeCommand: will be added on EC2 instance user_data to include new nodes on cluster

      sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CHECKSUM> <roles>

    2. Configure the Cloud Provider​

    On AWS EC2, we should create a few objects to configure our system. We've defined three distinct groups and IAM profiles to configure on AWS.

    1. Autoscaling group: Nodes that will be part of the EC2 Auto Scaling Group (ASG). The ASG will be used by cluster-autoscaler to scale up and down.

    • IAM profile: Required by k8s nodes where cluster-autoscaler will be running. It is recommended for Kubernetes master nodes. This profile is called K8sAutoscalerProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeAutoScalingInstances",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:SetDesiredCapacity",
                      "autoscaling:TerminateInstanceInAutoScalingGroup",
                      "autoscaling:DescribeTags",
                      "autoscaling:DescribeLaunchConfigurations",
                      "ec2:DescribeLaunchTemplateVersions"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
    1. Master group: Nodes that will be part of the Kubernetes etcd and/or control planes. This will be out of the ASG.

    • IAM profile: Required by the Kubernetes cloud_provider integration. Optionally, AWS_ACCESS_KEY and AWS_SECRET_KEY can be used instead using-aws-credentials. This profile is called K8sMasterProfile.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeLaunchConfigurations",
                      "autoscaling:DescribeTags",
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ec2:DescribeRouteTables",
                      "ec2:DescribeSecurityGroups",
                      "ec2:DescribeSubnets",
                      "ec2:DescribeVolumes",
                      "ec2:CreateSecurityGroup",
                      "ec2:CreateTags",
                      "ec2:CreateVolume",
                      "ec2:ModifyInstanceAttribute",
                      "ec2:ModifyVolume",
                      "ec2:AttachVolume",
                      "ec2:AuthorizeSecurityGroupIngress",
                      "ec2:CreateRoute",
                      "ec2:DeleteRoute",
                      "ec2:DeleteSecurityGroup",
                      "ec2:DeleteVolume",
                      "ec2:DetachVolume",
                      "ec2:RevokeSecurityGroupIngress",
                      "ec2:DescribeVpcs",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:AttachLoadBalancerToSubnets",
                      "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancer",
                      "elasticloadbalancing:CreateLoadBalancerPolicy",
                      "elasticloadbalancing:CreateLoadBalancerListeners",
                      "elasticloadbalancing:ConfigureHealthCheck",
                      "elasticloadbalancing:DeleteLoadBalancer",
                      "elasticloadbalancing:DeleteLoadBalancerListeners",
                      "elasticloadbalancing:DescribeLoadBalancers",
                      "elasticloadbalancing:DescribeLoadBalancerAttributes",
                      "elasticloadbalancing:DetachLoadBalancerFromSubnets",
                      "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
                      "elasticloadbalancing:ModifyLoadBalancerAttributes",
                      "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
                      "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
                      "elasticloadbalancing:AddTags",
                      "elasticloadbalancing:CreateListener",
                      "elasticloadbalancing:CreateTargetGroup",
                      "elasticloadbalancing:DeleteListener",
                      "elasticloadbalancing:DeleteTargetGroup",
                      "elasticloadbalancing:DescribeListeners",
                      "elasticloadbalancing:DescribeLoadBalancerPolicies",
                      "elasticloadbalancing:DescribeTargetGroups",
                      "elasticloadbalancing:DescribeTargetHealth",
                      "elasticloadbalancing:ModifyListener",
                      "elasticloadbalancing:ModifyTargetGroup",
                      "elasticloadbalancing:RegisterTargets",
                      "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
                      "iam:CreateServiceLinkedRole",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage",
                      "kms:DescribeKey"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }

      • IAM role: K8sMasterRole: [K8sMasterProfile,K8sAutoscalerProfile]

      • Security group: K8sMasterSg More info atRKE ports (custom nodes tab)

      • Tags: kubernetes.io/cluster/<clusterID>: owned

      • User data: K8sMasterUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add etcd+controlplane node to the k8s cluster

        #!/bin/bash -x

        cat <<EOF > /etc/sysctl.d/90-kubelet.conf
        vm.overcommit_memory = 1
        vm.panic_on_oom = 0
        kernel.panic = 10
        kernel.panic_on_oops = 1
        kernel.keys.root_maxkeys = 1000000
        kernel.keys.root_maxbytes = 25000000
        EOF
        sysctl -p /etc/sysctl.d/90-kubelet.conf

        curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
        sudo usermod -aG docker ubuntu

        TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
        PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
        PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
        K8S_ROLES="--etcd --controlplane"

        sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}
    1. Worker group: Nodes that will be part of the k8s worker plane. Worker nodes will be scaled by cluster-autoscaler using the ASG.

    • IAM profile: Provides cloud_provider worker integration. This profile is called K8sWorkerProfile.

      ```json
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ec2:DescribeInstances",
                      "ec2:DescribeRegions",
                      "ecr:GetAuthorizationToken",
                      "ecr:BatchCheckLayerAvailability",
                      "ecr:GetDownloadUrlForLayer",
                      "ecr:GetRepositoryPolicy",
                      "ecr:DescribeRepositories",
                      "ecr:ListImages",
                      "ecr:BatchGetImage"
                  ],
                  "Resource": "*"
              }
          ]
      }
      ```

    • IAM role: K8sWorkerRole: [K8sWorkerProfile]

    • Security group: K8sWorkerSg More info at RKE ports (custom nodes tab)

    • Tags:

      • kubernetes.io/cluster/<clusterID>: owned
      • k8s.io/cluster-autoscaler/<clusterName>: true
      • k8s.io/cluster-autoscaler/enabled: true

    • User data: K8sWorkerUserData Ubuntu 18.04(ami-0e11cbb34015ff725), installs docker and add worker node to the k8s cluster

      #!/bin/bash -x

      cat <<EOF > /etc/sysctl.d/90-kubelet.conf
      vm.overcommit_memory = 1
      vm.panic_on_oom = 0
      kernel.panic = 10
      kernel.panic_on_oops = 1
      kernel.keys.root_maxkeys = 1000000
      kernel.keys.root_maxbytes = 25000000
      EOF
      sysctl -p /etc/sysctl.d/90-kubelet.conf

      curl -sL https://releases.rancher.com/install-docker/19.03.sh | sh
      sudo usermod -aG docker ubuntu

      TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
      PRIVATE_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/local-ipv4)
      PUBLIC_IP=$(curl -H "X-aws-ec2-metadata-token: ${TOKEN}" -s http://169.254.169.254/latest/meta-data/public-ipv4)
      K8S_ROLES="--worker"

      sudo docker run -d --privileged --restart=unless-stopped --net=host -v /etc/kubernetes:/etc/kubernetes -v /var/run:/var/run rancher/rancher-agent:<RANCHER_VERSION> --server https://<RANCHER_URL> --token <RANCHER_TOKEN> --ca-checksum <RANCHER_CA_CHECKCSUM> --address ${PUBLIC_IP} --internal-address ${PRIVATE_IP} ${K8S_ROLES}

    More info is at RKE clusters on AWS and Cluster Autoscaler on AWS.

    3. Deploy Nodes​

    Once we've configured AWS, let's create VMs to bootstrap our cluster:

    • master (etcd+controlplane): Depending your needs, deploy three master instances with proper size. More info is at the recommendations for production-ready clusters.

      • IAM role: K8sMasterRole
      • Security group: K8sMasterSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
      • User data: K8sMasterUserData

    • worker: Define an ASG on EC2 with the following settings:

      • Name: K8sWorkerAsg
      • IAM role: K8sWorkerRole
      • Security group: K8sWorkerSg
      • Tags:
        • kubernetes.io/cluster/<clusterID>: owned
        • k8s.io/cluster-autoscaler/<clusterName>: true
        • k8s.io/cluster-autoscaler/enabled: true
      • User data: K8sWorkerUserData
      • Instances:
        • minimum: 2
        • desired: 2
        • maximum: 10

    Once the VMs are deployed, you should have a Rancher custom cluster up and running with three master and two worker nodes.

    4. Install Cluster-autoscaler​

    At this point, we should have rancher cluster up and running. We are going to install cluster-autoscaler on master nodes and kube-system namespace, following cluster-autoscaler recommendation.

    Parameters​

    This table shows cluster-autoscaler parameters for fine tuning:

    ParameterDefaultDescription
    cluster-name-Autoscaled cluster name, if available
    address:8085The address to expose Prometheus metrics
    kubernetes-Kubernetes master location. Leave blank for default
    kubeconfig-Path to kubeconfig file with authorization and master location information
    cloud-config-The path to the cloud provider configuration file. Empty string for no configuration file
    namespace"kube-system"Namespace in which cluster-autoscaler run
    scale-down-enabledtrueShould CA scale down the cluster
    scale-down-delay-after-add"10m"How long after scale up that scale down evaluation resumes
    scale-down-delay-after-delete0How long after node deletion that scale down evaluation resumes, defaults to scanInterval
    scale-down-delay-after-failure"3m"How long after scale down failure that scale down evaluation resumes
    scale-down-unneeded-time"10m"How long a node should be unneeded before it is eligible for scale down
    scale-down-unready-time"20m"How long an unready node should be unneeded before it is eligible for scale down
    scale-down-utilization-threshold0.5Sum of cpu or memory of all pods running on the node divided by node's corresponding allocatable resource, below which a node can be considered for scale down
    scale-down-gpu-utilization-threshold0.5Sum of gpu requests of all pods running on the node divided by node's allocatable resource, below which a node can be considered for scale down
    scale-down-non-empty-candidates-count30Maximum number of non empty nodes considered in one iteration as candidates for scale down with drain
    scale-down-candidates-pool-ratio0.1A ratio of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    scale-down-candidates-pool-min-count50Minimum number of nodes that are considered as additional non empty candidates for scale down when some candidates from previous iteration are no longer valid
    node-deletion-delay-timeout"2m"Maximum time CA waits for removing delay-deletion.cluster-autoscaler.kubernetes.io/ annotations before deleting the node
    scan-interval"10s"How often cluster is reevaluated for scale up or down
    max-nodes-total0Maximum number of nodes in all node groups. Cluster autoscaler will not grow the cluster beyond this number
    cores-total"0:320000"Minimum and maximum number of cores in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    memory-total"0:6400000"Minimum and maximum number of gigabytes of memory in cluster, in the format <min>:<max>. Cluster autoscaler will not scale the cluster beyond these numbers
    cloud-provider-Cloud provider type
    max-bulk-soft-taint-count10Maximum number of nodes that can be tainted/untainted PreferNoSchedule at the same time. Set to 0 to turn off such tainting
    max-bulk-soft-taint-time"3s"Maximum duration of tainting/untainting nodes as PreferNoSchedule at the same time
    max-empty-bulk-delete10Maximum number of empty nodes that can be deleted at the same time
    max-graceful-termination-sec600Maximum number of seconds CA waits for pod termination when trying to scale down a node
    max-total-unready-percentage45Maximum percentage of unready nodes in the cluster. After this is exceeded, CA halts operations
    ok-total-unready-count3Number of allowed unready nodes, irrespective of max-total-unready-percentage
    scale-up-from-zerotrueShould CA scale up when there 0 ready nodes
    max-node-provision-time"15m"Maximum time CA waits for node to be provisioned
    nodes-sets min,max size and other configuration data for a node group in a format accepted by cloud provider. Can be used multiple times. Format: <min>:<max>:<other...>
    node-group-auto-discovery-One or more definition(s) of node group auto-discovery. A definition is expressed <name of discoverer>:[<key>[=<value>]]
    estimator-"binpacking"
    expander"random"Type of node group expander to be used in scale up. Available values: ["random","most-pods","least-waste","price","priority"]
    ignore-daemonsets-utilizationfalseShould CA ignore DaemonSet pods when calculating resource utilization for scaling down
    ignore-mirror-pods-utilizationfalseShould CA ignore Mirror pods when calculating resource utilization for scaling down
    write-status-configmaptrueShould CA write status information to a configmap
    max-inactivity"10m"Maximum time from last recorded autoscaler activity before automatic restart
    max-failing-time"15m"Maximum time from last recorded successful autoscaler run before automatic restart
    balance-similar-node-groupsfalseDetect similar node groups and balance the number of nodes between them
    node-autoprovisioning-enabledfalseShould CA autoprovision node groups when needed
    max-autoprovisioned-node-group-count15The maximum number of autoprovisioned groups in the cluster
    unremovable-node-recheck-timeout"5m"The timeout before we check again a node that couldn't be removed before
    expendable-pods-priority-cutoff-10Pods with priority below cutoff will be expendable. They can be killed without any consideration during scale down and they don't cause scale up. Pods with null priority (PodPriority disabled) are non expendable
    regionalfalseCluster is regional
    new-pod-scale-up-delay"0s"Pods less than this old will not be considered for scale-up
    ignore-taint-Specifies a taint to ignore in node templates when considering to scale a node group
    balancing-ignore-label-Specifies a label to ignore in addition to the basic and cloud-provider set of labels when comparing if two node groups are similar
    aws-use-static-instance-listfalseShould CA fetch instance types in runtime or use a static list. AWS only
    profilingfalseIs debug/pprof endpoint enabled

    Deployment​

    Based on cluster-autoscaler-run-on-master.yaml example, we've created our own cluster-autoscaler-deployment.yaml to use preferred auto-discovery setup, updating tolerations, nodeSelector, image version and command config:

    ---
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
      name: cluster-autoscaler
      namespace: kube-system
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["events", "endpoints"]
        verbs: ["create", "patch"]
      - apiGroups: [""]
        resources: ["pods/eviction"]
        verbs: ["create"]
      - apiGroups: [""]
        resources: ["pods/status"]
        verbs: ["update"]
      - apiGroups: [""]
        resources: ["endpoints"]
        resourceNames: ["cluster-autoscaler"]
        verbs: ["get", "update"]
      - apiGroups: [""]
        resources: ["nodes"]
        verbs: ["watch", "list", "get", "update"]
      - apiGroups: [""]
        resources:
          - "pods"
          - "services"
          - "replicationcontrollers"
          - "persistentvolumeclaims"
          - "persistentvolumes"
        verbs: ["watch", "list", "get"]
      - apiGroups: ["extensions"]
        resources: ["replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["policy"]
        resources: ["poddisruptionbudgets"]
        verbs: ["watch", "list"]
      - apiGroups: ["apps"]
        resources: ["statefulsets", "replicasets", "daemonsets"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["storage.k8s.io"]
        resources: ["storageclasses", "csinodes"]
        verbs: ["watch", "list", "get"]
      - apiGroups: ["batch", "extensions"]
        resources: ["jobs"]
        verbs: ["get", "list", "watch", "patch"]
      - apiGroups: ["coordination.k8s.io"]
        resources: ["leases"]
        verbs: ["create"]
      - apiGroups: ["coordination.k8s.io"]
        resourceNames: ["cluster-autoscaler"]
        resources: ["leases"]
        verbs: ["get", "update"]
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    rules:
      - apiGroups: [""]
        resources: ["configmaps"]
        verbs: ["create","list","watch"]
      - apiGroups: [""]
        resources: ["configmaps"]
        resourceNames: ["cluster-autoscaler-status", "cluster-autoscaler-priority-expander"]
        verbs: ["delete", "get", "update", "watch"]

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: cluster-autoscaler
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        k8s-addon: cluster-autoscaler.addons.k8s.io
        k8s-app: cluster-autoscaler
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: Role
      name: cluster-autoscaler
    subjects:
      - kind: ServiceAccount
        name: cluster-autoscaler
        namespace: kube-system

    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: cluster-autoscaler
      namespace: kube-system
      labels:
        app: cluster-autoscaler
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: cluster-autoscaler
      template:
        metadata:
          labels:
            app: cluster-autoscaler
          annotations:
            prometheus.io/scrape: 'true'
            prometheus.io/port: '8085'
        spec:
          serviceAccountName: cluster-autoscaler
          tolerations:
            - effect: NoSchedule
              operator: "Equal"
              value: "true"
              key: node-role.kubernetes.io/controlplane
          nodeSelector:
            node-role.kubernetes.io/controlplane: "true"
          containers:
            - image: eu.gcr.io/k8s-artifacts-prod/autoscaling/cluster-autoscaler:<VERSION>
              name: cluster-autoscaler
              resources:
                limits:
                  cpu: 100m
                  memory: 300Mi
                requests:
                  cpu: 100m
                  memory: 300Mi
              command:
                - ./cluster-autoscaler
                - --v=4
                - --stderrthreshold=info
                - --cloud-provider=aws
                - --skip-nodes-with-local-storage=false
                - --expander=least-waste
                - --node-group-auto-discovery=asg:tag=k8s.io/cluster-autoscaler/enabled,k8s.io/cluster-autoscaler/<clusterName>
              volumeMounts:
                - name: ssl-certs
                  mountPath: /etc/ssl/certs/ca-certificates.crt
                  readOnly: true
              imagePullPolicy: "Always"
          volumes:
            - name: ssl-certs
              hostPath:
                path: "/etc/ssl/certs/ca-certificates.crt"

    Once the manifest file is prepared, deploy it in the Kubernetes cluster (Rancher UI can be used instead):

    kubectl -n kube-system apply -f cluster-autoscaler-deployment.yaml

    Note: Cluster-autoscaler deployment can also be set up using manual configuration

    Testing

    At this point, we should have a cluster-scaler up and running in our Rancher custom cluster. Cluster-scale should manage K8sWorkerAsg ASG to scale up and down between 2 and 10 nodes, when one of the following conditions is true:

    • There are pods that failed to run in the cluster due to insufficient resources. In this case, the cluster is scaled up.
    • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes. In this case, the cluster is scaled down.

    Generating Load​

    We've prepared a test-deployment.yaml just to generate load on the Kubernetes cluster and see if cluster-autoscaler is working properly. The test deployment is requesting 1000m CPU and 1024Mi memory by three replicas. Adjust the requested resources and/or replica to be sure you exhaust the Kubernetes cluster resources:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      labels:
        app: hello-world
      name: hello-world
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: hello-world
      strategy:
        rollingUpdate:
          maxSurge: 1
          maxUnavailable: 0
        type: RollingUpdate
      template:
        metadata:
          labels:
            app: hello-world
        spec:
          containers:
          - image: rancher/hello-world
            imagePullPolicy: Always
            name: hello-world
            ports:
            - containerPort: 80
              protocol: TCP
            resources:
              limits:
                cpu: 1000m
                memory: 1024Mi
              requests:
                cpu: 1000m
                memory: 1024Mi

    Once the test deployment is prepared, deploy it in the Kubernetes cluster default namespace (Rancher UI can be used instead):

    kubectl -n default apply -f test-deployment.yaml

    Checking Scale​

    Once the Kubernetes resources got exhausted, cluster-autoscaler should scale up worker nodes where pods failed to be scheduled. It should scale up until up until all pods became scheduled. You should see the new nodes on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Once scale up is checked, let check for scale down. To do it, reduce the replica number on the test deployment until you release enough Kubernetes cluster resources to scale down. You should see nodes disappear on the ASG and on the Kubernetes cluster. Check the logs on the kube-system cluster-autoscaler pod.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html index ad078320d73..bd3a6837347 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/nodes-and-node-pools.html @@ -5,13 +5,13 @@ Nodes and Node Pools | Rancher Manager - +
    Version: v2.5

    Nodes and Node Pools

    After you launch a Kubernetes cluster in Rancher, you can manage individual nodes from the cluster's Node tab. Depending on the option used to provision the cluster, there are different node options available.

    If you want to manage the cluster and not individual nodes, see Editing Clusters.

    Node Options Available for Each Cluster Creation Option

    The following table lists which node options are available for each type of cluster in Rancher. Click the links in the Option column for more detailed information about each feature.

    OptionNodes Hosted by an Infrastructure ProviderCustom NodeHosted ClusterRegistered EKS NodesAll Other Registered NodesDescription
    Cordon✓✓✓✓✓Marks the node as unschedulable.
    Drain✓✓✓✓✓Marks the node as unschedulable and evicts all pods.
    Edit✓✓✓✓✓Enter a custom name, description, label, or taints for a node.
    View API✓✓✓✓✓View API data.
    Delete✓✓**Deletes defective nodes from the cluster.
    Download Keys✓Download SSH key in order to SSH into the node.
    Node Scaling✓✓Scale the number of nodes in the node pool up or down.

    * Delete option accessible via View API

    Nodes Hosted by an Infrastructure Provider​

    Node pools are available when you provision Rancher-launched Kubernetes clusters on nodes that are hosted in an infrastructure provider.

    Clusters provisioned using one of the node pool options can be scaled up or down if the node pool is edited.

    A node pool can also automatically maintain the node scale that's set during the initial cluster provisioning if node auto-replace is enabled. This scale determines the number of active nodes that Rancher maintains for the cluster.

    Rancher uses node templates to replace nodes in the node pool. Each node template uses cloud provider credentials to allow Rancher to set up the node in the infrastructure provider.

    Nodes Provisioned by Hosted Kubernetes Providers​

    Options for managing nodes hosted by a Kubernetes provider are somewhat limited in Rancher. Rather than using the Rancher UI to make edits such as scaling the number of nodes up or down, edit the cluster directly.

    Registered Nodes​

    Although you can deploy workloads to a registered cluster using Rancher, you cannot manage individual cluster nodes. All management of imported cluster nodes must take place outside of Rancher.

    Managing and Editing Individual Nodes

    Editing a node lets you:

    • Change its name
    • Change its description
    • Add labels
    • Add/Remove taints

    To manage individual nodes, browse to the cluster that you want to manage and then select Nodes from the main menu. You can open the options menu for a node by clicking its ⋮ icon (...).

    Viewing a Node in the Rancher API

    Select this option to view the node's API endpoints.

    Deleting a Node

    Use Delete to remove defective nodes from the cloud provider.

    When you the delete a defective node, Rancher can automatically replace it with an identically provisioned node if the node is in a node pool and node auto-replace is enabled.

    Tip: If your cluster is hosted by an infrastructure provider, and you want to scale your cluster down instead of deleting a defective node, scale down rather than delete.

    Scaling Nodes

    For nodes hosted by an infrastructure provider, you can scale the number of nodes in each node pool by using the scale controls. This option isn't available for other cluster types.

    SSH into a Node Hosted by an Infrastructure Provider

    For nodes hosted by an infrastructure provider, you have the option of downloading its SSH key so that you can connect to it remotely from your desktop.

    1. From the cluster hosted by an infrastructure provider, select Nodes from the main menu.

    2. Find the node that you want to remote into. Select ⋮ > Download Keys.

      Step Result: A ZIP file containing files used for SSH is downloaded.

    3. Extract the ZIP file to any location.

    4. Open Terminal. Change your location to the extracted ZIP file.

    5. Enter the following command:

      ssh -i id_rsa root@<IP_OF_HOST>

    Cordoning a Node

    Cordoning a node marks it as unschedulable. This feature is useful for performing short tasks on the node during small maintenance windows, like reboots, upgrades, or decommissions. When you're done, power back on and make the node schedulable again by uncordoning it.

    Draining a Node

    Draining is the process of first cordoning the node, and then evicting all its pods. This feature is useful for performing node maintenance (like kernel upgrades or hardware maintenance). It prevents new pods from deploying to the node while redistributing existing pods so that users don't experience service interruption.

    • For pods with a replica set, the pod is replaced by a new pod that will be scheduled to a new node. Additionally, if the pod is part of a service, then clients will automatically be redirected to the new pod.

    • For pods with no replica set, you need to bring up a new copy of the pod, and assuming it is not part of a service, redirect clients to it.

    You can drain nodes that are in either a cordoned or active state. When you drain a node, the node is cordoned, the nodes are evaluated for conditions they must meet to be drained, and then (if it meets the conditions) the node evicts its pods.

    However, you can override the conditions draining when you initiate the drain. You're also given an opportunity to set a grace period and timeout value.

    Aggressive and Safe Draining Options​

    There are two drain modes: aggressive and safe.

    • Aggressive Mode

      In this mode, pods won't get rescheduled to a new node, even if they do not have a controller. Kubernetes expects you to have your own logic that handles the deletion of these pods.

      Kubernetes also expects the implementation to decide what to do with pods using emptyDir. If a pod uses emptyDir to store local data, you might not be able to safely delete it, since the data in the emptyDir will be deleted once the pod is removed from the node. Choosing aggressive mode will delete these pods.

    • Safe Mode

      If a node has standalone pods or ephemeral data it will be cordoned but not drained.

    Grace Period​

    The timeout given to each pod for cleaning things up, so they will have chance to exit gracefully. For example, when pods might need to finish any outstanding requests, roll back transactions or save state to some external storage. If negative, the default value specified in the pod will be used.

    Timeout​

    The amount of time drain should continue to wait before giving up.

    Kubernetes Known Issue: The timeout setting was not enforced while draining a node before Kubernetes 1.12.

    Drained and Cordoned State​

    If there's any error related to user input, the node enters a cordoned state because the drain failed. You can either correct the input and attempt to drain the node again, or you can abort by uncordoning the node.

    If the drain continues without error, the node enters a draining state. You'll have the option to stop the drain when the node is in this state, which will stop the drain process and change the node's state to cordoned.

    Once drain successfully completes, the node will be in a state of drained. You can then power off or delete the node.

    Want to know more about cordon and drain? See the Kubernetes documentation.

    Labeling a Node to be Ignored by Rancher

    Some solutions, such as F5's BIG-IP integration, may require creating a node that is never registered to a cluster.

    Since the node will never finish registering, it will always be shown as unhealthy in the Rancher UI.

    In that case, you may want to label the node to be ignored by Rancher so that Rancher only shows nodes as unhealthy when they are actually failing.

    You can label nodes to be ignored by using a setting in the Rancher UI, or by using kubectl.

    Note: There is an open issue in which nodes labeled to be ignored can get stuck in an updating state.

    Labeling Nodes to be Ignored with kubectl​

    To add a node that will be ignored by Rancher, use kubectl to create a node that has the following label:

    cattle.rancher.io/node-status: ignore

    Result: If you add the node to a cluster, Rancher will not attempt to sync with this node. The node can still be part of the cluster and can be listed with kubectl.

    If the label is added before the node is added to the cluster, the node will not be shown in the Rancher UI.

    If the label is added after the node is added to a Rancher cluster, the node will not be removed from the UI.

    If you delete the node from the Rancher server using the Rancher UI or API, the node will not be removed from the cluster if the nodeName is listed in the Rancher settings in the Rancher API under v3/settings/ignore-node-name.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html index 789d797e73f..96dc6adf7da 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/projects-and-namespaces.html @@ -5,13 +5,13 @@ Projects and Kubernetes Namespaces with Rancher | Rancher Manager - +
    Version: v2.5

    Projects and Kubernetes Namespaces with Rancher

    A namespace is a Kubernetes concept that allows a virtual cluster within a cluster, which is useful for dividing the cluster into separate "virtual clusters" that each have their own access control and resource quotas.

    A project is a group of namespaces, and it is a concept introduced by Rancher. Projects allow you to manage multiple namespaces as a group and perform Kubernetes operations in them. You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    This section describes how projects and namespaces work with Rancher.

    About Namespaces​

    A namespace is a concept introduced by Kubernetes. According to the official Kubernetes documentation on namespaces,

    Kubernetes supports multiple virtual clusters backed by the same physical cluster. These virtual clusters are called namespaces. [...] Namespaces are intended for use in environments with many users spread across multiple teams, or projects. For clusters with a few to tens of users, you should not need to create or think about namespaces at all.

    Namespaces provide the following functionality:

    • Providing a scope for names: Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace.
    • Resource quotas: Namespaces provide a way to divide cluster resources between multiple users.

    You can assign resources at the project level so that each namespace in the project can use them. You can also bypass this inheritance by assigning resources explicitly to a namespace.

    You can assign the following resources directly to namespaces:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    For more information on creating and moving namespaces, see Namespaces.

    Role-based access control issues with namespaces and kubectl​

    Because projects are a concept introduced by Rancher, kubectl does not have the capability to restrict the creation of namespaces to a project the creator has access to.

    This means that when standard users with project-scoped permissions create a namespaces with kubectl, it may be unusable because kubectl doesn't require the new namespace to be scoped within a certain project.

    If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    If a standard user is a project owner, the user will be able to create namespaces within that project. The Rancher UI will prevent that user from creating namespaces outside the scope of the projects they have access to.

    About Projects​

    In terms of hierarchy:

    • Clusters contain projects
    • Projects contain namespaces

    You can use projects to support multi-tenancy, so that a team can access a project within a cluster without having access to other projects in the same cluster.

    In the base version of Kubernetes, features like role-based access rights or cluster resources are assigned to individual namespaces. A project allows you to save time by giving an individual or a team access to multiple namespaces simultaneously.

    You can use projects to perform actions such as:

    • Assign users to a group of namespaces (i.e., project membership).
    • Assign users specific roles in a project. A role can be owner, member, read-only, or custom.
    • Assign resources to the project.
    • Assign Pod Security Policies.

    When you create a cluster, two projects are automatically created within it:

    The Cluster's Default Project​

    When you provision a cluster with Rancher, it automatically creates a default project for the cluster. This is a project you can use to get started with your cluster, but you can always delete it and replace it with projects that have more descriptive names.

    If you don't have a need for more than the default namespace, you also do not need more than the Default project in Rancher.

    If you require another level of organization beyond the Default project, you can create more projects in Rancher to isolate namespaces, applications and resources.

    The System Project​

    When troubleshooting, you can view the system project to check if important namespaces in the Kubernetes system are working properly. This easily accessible project saves you from troubleshooting individual system namespace containers.

    To open it, open the Global menu, and then select the system project for your cluster.

    The system project:

    • Is automatically created when you provision a cluster.
    • Lists all namespaces that exist in v3/settings/system-namespaces, if they exist.
    • Allows you to add more namespaces or move its namespaces to other projects.
    • Cannot be deleted because it's required for cluster operations.

    Note: In RKE clusters where the project network isolation option is enabled, the system project overrides the project network isolation option so that it can communicate with other projects, collect logs, and check health.

    Project Authorization​

    Standard users are only authorized for project access in two situations:

    • An administrator, cluster owner or cluster member explicitly adds the standard user to the project's Members tab.
    • Standard users can access projects that they create themselves.

    Pod Security Policies​

    Rancher extends Kubernetes to allow the application of Pod Security Policies at the project level in addition to the cluster level. However, as a best practice, we recommend applying Pod Security Policies at the cluster level.

    Creating Projects​

    This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.

    1. Name a new project.
    2. Optional: Select a pod security policy.
    3. Recommended: Add project members.
    4. Optional: Add resource quotas.

    1. Name a New Project​

    1. From the Global view, choose Clusters from the main menu. From the Clusters page, open the cluster from which you want to create a project.

    2. From the main menu, choose Projects/Namespaces. Then click Add Project.

    3. Enter a Project Name.

    2. Optional: Select a Pod Security Policy​

    This option is only available if you've already created a Pod Security Policy. For instruction, see Creating Pod Security Policies.

    Assigning a PSP to a project will:

    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.

    Use the Members section to provide other users with project access and roles.

    By default, your user is added as the project Owner.

    Notes on Permissions:

    • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

    • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

    • Choose Custom to create a custom role on the fly: Custom Project Roles.

    To add members:

    1. Click Add Member.
    2. From the Name combo box, search for a user or group that you want to assign project access. Note: You can only search for groups if external authentication is enabled.
    3. From the Role drop-down, choose a role. For more information, refer to the documentation on project roles.

    4. Optional: Add Resource Quotas​

    Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see Resource Quotas.

    To add a resource quota,

    1. Click Add Quota.
    2. Select a Resource Type. For more information, see Resource Quotas..
    3. Enter values for the Project Limit and the Namespace Default Limit.
    4. Optional: Specify Container Default Resource Limit, which will be applied to every container started in the project. The parameter is recommended if you have CPU or Memory limits set by the Resource Quota. It can be overridden on per an individual namespace or a container level. For more information, see Container Default Resource Limit
    5. Click Create.

    Result: Your project is created. You can view it from the cluster's Projects/Namespaces view.

    FieldDescription
    Project LimitThe overall resource limit for the project.
    Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project when created. The combined limit of all project namespaces shouldn't exceed the project limit.

    Switching between Clusters and Projects​

    To switch between clusters and projects, use the Global drop-down available in the main menu.

    Global Menu

    Alternatively, you can switch between projects and clusters using the main menu.

    • To switch between clusters, open the Global view and select Clusters from the main menu. Then open a cluster.
    • To switch between projects, open a cluster, and then select Projects/Namespaces from the main menu. Select the link for the project that you want to open.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html index dccb88c0b38..19cd94488bc 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates.html @@ -5,13 +5,13 @@ Certificate Rotation | Rancher Manager - +
    Version: v2.5

    Certificate Rotation

    Warning: Rotating Kubernetes certificates may result in your cluster being temporarily unavailable as components are restarted. For production environments, it's recommended to perform this action during a maintenance window.

    By default, Kubernetes clusters require certificates and Rancher launched Kubernetes clusters automatically generate certificates for the Kubernetes components. Rotating these certificates is important before the certificates expire as well as if a certificate is compromised. After the certificates are rotated, the Kubernetes components are automatically restarted.

    Certificates can be rotated for the following services:

    • etcd
    • kubelet (node certificate)
    • kubelet (serving certificate, if enabled)
    • kube-apiserver
    • kube-proxy
    • kube-scheduler
    • kube-controller-manager

    Certificate Rotation​

    Rancher launched Kubernetes clusters have the ability to rotate the auto-generated certificates through the UI.

    1. In the Global view, navigate to the cluster that you want to rotate certificates.

    2. Select ⋮ > Rotate Certificates.

    3. Select which certificates that you want to rotate.

      • Rotate all Service certificates (keep the same CA)
      • Rotate an individual service and choose one of the services from the drop-down menu

    4. Click Save.

    Results: The selected certificates will be rotated and the related services will be restarted to start using the new certificate.

    Note: Even though the RKE CLI can use custom certificates for the Kubernetes cluster components, Rancher currently doesn't allow the ability to upload these in Rancher launched Kubernetes clusters.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html index 288f383f36a..33b84ddf87f 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/add-users-to-projects.html @@ -5,13 +5,13 @@ Adding Users to Projects | Rancher Manager - +
    Version: v2.5

    Adding Users to Projects

    If you want to provide a user with access and permissions to specific projects and resources within a cluster, assign the user a project membership.

    You can add members to a project as it is created, or add them to an existing project.

    Tip: Want to provide a user with access to all projects within a cluster? See Adding Cluster Members instead.

    Adding Members to a New Project​

    You can add members to a project as you create it (recommended if possible). For details on creating a new project, refer to the cluster administration section.

    Adding Members to an Existing Project​

    Following project creation, you can add users as project members so that they can access its resources.

    1. From the Global view, open the project that you want to add members to.

    2. From the main menu, select Members. Then click Add Member.

    3. Search for the user or group that you want to add to the project.

      If external authentication is configured:

      • Rancher returns users from your external authentication source as you type.

      • A drop-down allows you to add groups instead of individual users. The dropdown only lists groups that you, the logged in user, are included in.

      Note: If you are logged in as a local user, external users do not display in your search results.

    4. Assign the user or group Project roles.

      What are Project Roles?

      Notes:

      • Users assigned the Owner or Member role for a project automatically inherit the namespace creation role. However, this role is a Kubernetes ClusterRole, meaning its scope extends to all projects in the cluster. Therefore, users explicitly assigned the Owner or Member role for a project can create namespaces in other projects they're assigned to, even with only the Read Only role assigned.

      • By default, the Rancher role of project-member inherits from the Kubernetes-edit role, and the project-owner role inherits from the Kubernetes-admin role. As such, both project-member and project-owner roles will allow for namespace management, including the ability to create and delete namespaces.

      • For Custom roles, you can modify the list of individual roles available for assignment.

    Result: The chosen users are added to the project.

    • To revoke project membership, select the user and click Delete. This action deletes membership, not the user.
    • To modify a user's roles in the project, delete them from the project, and then re-add them with modified roles.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html index ae779edd045..6a0d3f731a2 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/ci-cd-pipelines.html @@ -5,13 +5,13 @@ Rancher's CI/CD Pipelines | Rancher Manager - +
    Version: v2.5

    Rancher's CI/CD Pipelines

    Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

    After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

    • Build your application from code to image.
    • Validate your builds.
    • Deploy your build images to your cluster.
    • Run unit tests.
    • Run regression tests.

    For details, refer to the pipelines section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html index 354437be9b7..6ff9ea2b4d9 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-namespaces.html @@ -5,13 +5,13 @@ Namespaces | Rancher Manager - +
    Version: v2.5

    Namespaces

    Within Rancher, you can further divide projects into different namespaces, which are virtual clusters within a project backed by a physical cluster. Should you require another level of organization beyond projects and the default namespace, you can use multiple namespaces to isolate applications and resources.

    Although you assign resources at the project level so that each namespace in the project can use them, you can override this inheritance by assigning resources explicitly to a namespace.

    Resources that you can assign directly to namespaces include:

    To manage permissions in a vanilla Kubernetes cluster, cluster admins configure role-based access policies for each namespace. With Rancher, user permissions are assigned on the project level instead, and permissions are automatically inherited by any namespace owned by the particular project.

    Note: If you create a namespace with kubectl, it may be unusable because kubectl doesn't require your new namespace to be scoped within a project that you have access to. If your permissions are restricted to the project level, it is better to create a namespace through Rancher to ensure that you will have permission to access the namespace.

    Creating Namespaces​

    Create a new namespace to isolate apps and resources in a project.

    Tip: When working with project resources that you can assign to a namespace (i.e., workloads, certificates, ConfigMaps, etc.) you can create a namespace on the fly.

    1. From the Global view, open the project where you want to create a namespace.

      Tip: As a best practice, we recommend creating namespaces from the project level. However, cluster owners and members can create them from the cluster level as well.

    2. From the main menu, select Namespace. The click Add Namespace.

    3. Optional: If your project has Resource Quotas in effect, you can override the default resource Limits (which places a cap on the resources that the namespace can consume).

    4. Enter a Name and then click Create.

    Result: Your namespace is added to the project. You can begin assigning cluster resources to the namespace.

    Moving Namespaces to Another Project​

    Cluster admins and members may occasionally need to move a namespace to another project, such as when you want a different team to start using the application.

    1. From the Global view, open the cluster that contains the namespace you want to move.

    2. From the main menu, select Projects/Namespaces.

    3. Select the namespace(s) that you want to move to a different project. Then click Move. You can move multiple namespaces at one.

      Notes:

      • Don't move the namespaces in the System project. Moving these namespaces can adversely affect cluster networking.
      • You cannot move a namespace into a project that already has a resource quota configured.
      • If you move a namespace from a project that has a quota set to a project with no quota set, the quota is removed from the namespace.

    4. Choose a new project for the new namespace and then click Move. Alternatively, you can remove the namespace from all projects by selecting None.

    Result: Your namespace is moved to a different project (or is unattached from all projects). If any project resources are attached to the namespace, the namespace releases them and then attached resources from the new project.

    Editing Namespace Resource Quotas​

    You can always override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    For more information, see how to edit namespace resource quotas.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html index 919ef21e707..0e0d52fd085 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.html @@ -5,14 +5,14 @@ Pod Security Policies | Rancher Manager - +
    Version: v2.5

    Pod Security Policies

    These cluster options are only available for clusters in which Rancher has launched Kubernetes.

    You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.

    Prerequisites​

    Applying a Pod Security Policy​

    1. From the Global view, find the cluster containing the project you want to apply a PSP to.
    2. From the main menu, select Projects/Namespaces.
    3. Find the project that you want to add a PSP to. From that project, select ⋮ > Edit.
    4. From the Pod Security Policy drop-down, select the PSP you want to apply to the project. Assigning a PSP to a project will:
    • Override the cluster's default PSP.
    • Apply the PSP to the project.
    • Apply the PSP to any namespaces you add to the project later.
    1. Click Save.

    Result: The PSP is applied to the project and any namespaces added to the project.

    Note: Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html index 8bdbeb696c4..84121f0de82 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.html @@ -5,13 +5,13 @@ How Resource Quotas Work in Rancher Projects | Rancher Manager - +
    Version: v2.5

    How Resource Quotas Work in Rancher Projects

    Resource quotas in Rancher include the same functionality as the native version of Kubernetes. However, in Rancher, resource quotas have been extended so that you can apply them to projects.

    In a standard Kubernetes deployment, resource quotas are applied to individual namespaces. However, you cannot apply the quota to your namespaces simultaneously with a single action. Instead, the resource quota must be applied multiple times.

    In the following diagram, a Kubernetes administrator is trying to enforce a resource quota without Rancher. The administrator wants to apply a resource quota that sets the same CPU and memory limit to every namespace in his cluster (Namespace 1-4) . However, in the base version of Kubernetes, each namespace requires a unique resource quota. The administrator has to create four different resource quotas that have the same specs configured (Resource Quota 1-4) and apply them individually.

    Base Kubernetes: Unique Resource Quotas Being Applied to Each Namespace

    Native Kubernetes Resource Quota Implementation

    Resource quotas are a little different in Rancher. In Rancher, you apply a resource quota to the project, and then the quota propagates to each namespace, whereafter Kubernetes enforces your limits using the native version of resource quotas. If you want to change the quota for a specific namespace, you can override it.

    The resource quota includes two limits, which you set while creating or editing a project:

    • Project Limits:

      This set of values configures an overall resource limit for the project. If you try to add a new namespace to the project, Rancher uses the limits you've set to validate that the project has enough resources to accommodate the namespace. In other words, if you try to move a namespace into a project near its resource quota, Rancher blocks you from moving the namespace.

    • Namespace Default Limits:

      This value is the default resource limit available for each namespace. When the resource quota is created at the project level, this limit is automatically propagated to each namespace in the project. Each namespace is bound to this default limit unless you override it.

    In the following diagram, a Rancher administrator wants to apply a resource quota that sets the same CPU and memory limit for every namespace in their project (Namespace 1-4). However, in Rancher, the administrator can set a resource quota for the project (Project Resource Quota) rather than individual namespaces. This quota includes resource limits for both the entire project (Project Limit) and individual namespaces (Namespace Default Limit). Rancher then propagates the Namespace Default Limit quotas to each namespace (Namespace Resource Quota) when created.

    Rancher: Resource Quotas Propagating to Each Namespace

    Rancher Resource Quota Implementation

    Let's highlight some more nuanced functionality. If a quota is deleted at the project level, it will also be removed from all namespaces contained within that project, despite any overrides that may exist. Further, updating an existing namespace default limit for a quota at the project level will not result in that value being propagated to existing namespaces in the project; the updated value will only be applied to newly created namespaces in that project. To update a namespace default limit for existing namespaces you can delete and subsequently recreate the quota at the project level with the new default value. This will result in the new default value being applied to all existing namespaces in the project.

    The following table explains the key differences between the two quota types.

    Rancher Resource QuotasKubernetes Resource Quotas
    Applies to projects and namespace.Applies to namespaces only.
    Creates resource pool for all namespaces in project.Applies static resource limits to individual namespaces.
    Applies resource quotas to namespaces through propagation.Applies only to the assigned namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html index 331ee87c0cf..4b06f786956 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.html @@ -5,13 +5,13 @@ Overriding the Default Limit for a Namespace | Rancher Manager - +
    Version: v2.5

    Overriding the Default Limit for a Namespace

    Although the Namespace Default Limit propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace.

    In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for Namespace 3 so that it has more resources available. Therefore, the administrator raises the namespace limits for Namespace 3 so that the namespace can access more resources.

    Namespace Default Limit Override

    Namespace Default Limit Override

    How to: Editing Namespace Resource Quotas

    Editing Namespace Resource Quotas​

    If there is a resource quota configured for a project, you can override the namespace default limit to provide a specific namespace with access to more (or less) project resources.

    1. From the Global view, open the cluster that contains the namespace for which you want to edit the resource quota.

    2. From the main menu, select Projects/Namespaces.

    3. Find the namespace for which you want to edit the resource quota. Select ⋮ > Edit.

    4. Edit the Resource Quota Limits. These limits determine the resources available to the namespace. The limits must be set within the configured project limits.

      For more information about each Resource Type, see Resource Quotas.

      Note:

      • If a resource quota is not configured for the project, these options will not be available.
      • If you enter limits that exceed the configured project limits, Rancher will not let you save your edits.

    Result: Your override is applied to the namespace's resource quota.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html index 168533ace19..135414b4806 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.html @@ -5,13 +5,13 @@ Resource Quota Type Reference | Rancher Manager - +
    Version: v2.5

    Resource Quota Type Reference

    When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types.

    Resource TypeDescription
    CPU Limit*The maximum amount of CPU (in millicores) allocated to the project/namespace.1
    CPU Reservation*The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1
    Memory Limit*The maximum amount of memory (in bytes) allocated to the project/namespace.1
    Memory Reservation*The minimum amount of memory (in bytes) guaranteed to the project/namespace.1
    Storage ReservationThe minimum amount of storage (in gigabytes) guaranteed to the project/namespace.
    Services Load BalancersThe maximum number of load balancers services that can exist in the project/namespace.
    Services Node PortsThe maximum number of node port services that can exist in the project/namespace.
    PodsThe maximum number of pods that can exist in the project/namespace in a non-terminal state (i.e., pods with a state of .status.phase in (Failed, Succeeded) equal to true).
    ServicesThe maximum number of services that can exist in the project/namespace.
    ConfigMapsThe maximum number of ConfigMaps that can exist in the project/namespace.
    Persistent Volume ClaimsThe maximum number of persistent volume claims that can exist in the project/namespace.
    Replications ControllersThe maximum number of replication controllers that can exist in the project/namespace.
    SecretsThe maximum number of secrets that can exist in the project/namespace.

    * When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the Kubernetes documentation for more details on why this is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html index 0bca90eda2e..0a678a9f4d1 100644 --- a/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html +++ b/v2.5/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/set-container-default-resource-limits.html @@ -5,13 +5,13 @@ Setting Container Default Resource Limits | Rancher Manager - +
    Version: v2.5

    Setting Container Default Resource Limits

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. See the Kubernetes documentation for more details on why this is required.

    To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    Editing the Container Default Resource Limit​

    Edit container default resource limit when:

    • You have a CPU or Memory resource quota set on a project, and want to supply the corresponding default values for a container.
    • You want to edit the default container resource limit.
    1. From the Global view, open the cluster containing the project to which you want to edit the container default resource limit.
    2. From the main menu, select Projects/Namespaces.
    3. Find the project that you want to edit the container default resource limit. From that project, select ⋮ > Edit.
    4. Expand Container Default Resource Limit and edit the values.

    Resource Limit Propagation​

    When the default container resource limit is set at a project level, the parameter will be propagated to any namespace created in the project after the limit has been set. For any existing namespace in a project, this limit will not be automatically propagated. You will need to manually set the default container resource limit for any existing namespaces in the project in order for it to be used when creating any containers.

    You can set a default container resource limit on a project and launch any catalog applications.

    Once a container default resource limit is configured on a namespace, the default will be pre-populated for any containers created in that namespace. These limits/reservations can always be overridden during workload creation.

    Container Resource Quota Types​

    The following resource limits can be configured:

    Resource TypeDescription
    CPU LimitThe maximum amount of CPU (in millicores) allocated to the container.
    CPU ReservationThe minimum amount of CPU (in millicores) guaranteed to the container.
    Memory LimitThe maximum amount of memory (in bytes) allocated to the container.
    Memory ReservationThe minimum amount of memory (in bytes) guaranteed to the container.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html index 71431938a04..fc7d2ddc01b 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/create-persistent-grafana-dashboard.html @@ -5,13 +5,13 @@ Persistent Grafana Dashboards | Rancher Manager - +
    Version: v2.5

    Persistent Grafana Dashboards

    To allow the Grafana dashboard to persist after the Grafana instance restarts, add the dashboard configuration JSON into a ConfigMap. ConfigMaps also allow the dashboards to be deployed with a GitOps or CD based approach. This allows the dashboard to be put under version control.

    Creating a Persistent Grafana Dashboard

    Prerequisites:

    • The monitoring application needs to be installed.
    • To create the persistent dashboard, you must have at least the Manage Config Maps Rancher RBAC permissions assigned to you in the project or namespace that contains the Grafana Dashboards. This correlates to the monitoring-dashboard-edit or monitoring-dashboard-admin Kubernetes native RBAC Roles exposed by the Monitoring chart.
    • To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a project-member role.

    1. Get the JSON model of the dashboard that you want to persist​

    To create a persistent dashboard, you will need to get the JSON model of the dashboard you want to persist. You can use a premade dashboard or build your own.

    To use a premade dashboard, go to https://grafana.com/grafana/dashboards, open up its detail page, and click on the Download JSON button to get the JSON model for the next step.

    To use your own dashboard:

    1. Click on the link to open Grafana. From the Cluster Explorer, click Cluster Explorer > Monitoring.

    2. Log in to Grafana. Note: The default Admin username and password for the Grafana instance is admin/prom-operator. Alternative credentials can also be supplied on deploying or upgrading the chart.

      Note: Regardless of who has the password, in order to access the Grafana instance, you still need at least the Manage Services or View Monitoring permissions in the project that Rancher Monitoring is deployed into. Alternative credentials can also be supplied on deploying or upgrading the chart.

    3. Create a dashboard using Grafana's UI. Once complete, go to the dashboard's settings by clicking on the gear icon in the top navigation menu. In the left navigation menu, click JSON Model.

    4. Copy the JSON data structure that appears.

    2. Create a ConfigMap using the Grafana JSON model​

    Create a ConfigMap in the namespace that contains your Grafana Dashboards (e.g. cattle-dashboards by default).

    The ConfigMap should look like this:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      labels:
        grafana_dashboard: "1"
      name: <dashboard-name>
      namespace: cattle-dashboards # Change if using a non-default namespace
    data:
      <dashboard-name>.json: |-
        <copied-json>

    By default, Grafana is configured to watch all ConfigMaps with the grafana_dashboard label within the cattle-dashboards namespace.

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, refer to this section.

    To create the ConfigMap in the Rancher UI,

    1. Go to the Cluster Explorer.
    2. Click Core > ConfigMaps.
    3. Click Create.
    4. Set up the key-value pairs similar to the example above. When entering the value for <dashboard-name>.json, click Read from File to upload the JSON data model as the value.
    5. Click Create.

    Result: After the ConfigMap is created, it should show up on the Grafana UI and be persisted even if the Grafana pod is restarted.

    Dashboards that are persisted using ConfigMaps cannot be deleted or edited from the Grafana UI.

    If you attempt to delete the dashboard in the Grafana UI, you will see the error message "Dashboard cannot be deleted because it was provisioned." To delete the dashboard, you will need to delete the ConfigMap.

    Configuring Namespaces for the Grafana Dashboard ConfigMap​

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the rancher-monitoring Helm chart:

    grafana.sidecar.dashboards.searchNamespace=ALL

    Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in grafana.dashboards.namespace, which defaults to cattle-dashboards.

    Known Issues

    For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation helm.sh/resource-policy: "keep".

    This annotation will be added by default in the new monitoring chart released by Rancher v2.5.8, but it still needs to be manually applied for users of earlier Rancher versions.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html index 8f93e6b7e93..ccba7fee217 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/customize-grafana-dashboard.html @@ -5,13 +5,13 @@ Customizing Grafana Dashboards | Rancher Manager - +
    Version: v2.5

    Customizing Grafana Dashboards

    In this section, you'll learn how to customize the Grafana dashboard to show metrics that apply to a certain container.

    Prerequisites​

    Before you can customize a Grafana dashboard, the rancher-monitoring application must be installed.

    To see the links to the external monitoring UIs, including Grafana dashboards, you will need at least a project-member role.

    Signing in to Grafana​

    1. In the Rancher UI, go to the cluster that has the dashboard you want to customize.
    2. In the left navigation menu, click Monitoring.
    3. Click Grafana. The Grafana dashboard should open in a new tab.
    4. Go to the log in icon in the lower left corner and click Sign In.
    5. Log in to Grafana. The default Admin username and password for the Grafana instance is admin/prom-operator. (Regardless of who has the password, cluster administrator permission in Rancher is still required access the Grafana instance.) Alternative credentials can also be supplied on deploying or upgrading the chart.

    Getting the PromQL Query Powering a Grafana Panel​

    For any panel, you can click the title and click Explore to get the PromQL queries powering the graphic.

    For this example, we would like to get the CPU usage for the Alertmanager container, so we click CPU Utilization > Inspect.

    The Data tab shows the underlying data as a time series, with the time in first column and the PromQL query result in the second column. Copy the PromQL query.

    (1 - (avg(irate({__name__=~"node_cpu_seconds_total|windows_cpu_time_total",mode="idle"}[5m])))) * 100

    You can then modify the query in the Grafana panel or create a new Grafana panel using the query.

    See also:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html index 55a8ea34b0f..73f0d9ced76 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/debug-high-memory-usage.html @@ -5,13 +5,13 @@ Debugging High Memory Usage | Rancher Manager - +
    Version: v2.5

    Debugging High Memory Usage

    Every time series in Prometheus is uniquely identified by its metric name and optional key-value pairs called labels.

    The labels allow the ability to filter and aggregate the time series data, but they also multiply the amount of data that Prometheus collects.

    Each time series has a defined set of labels, and Prometheus generates a new time series for all unique combinations of labels. If a metric has two labels attached, two time series are generated for that metric. Changing any label value, including adding or removing a label, will create a new time series.

    Prometheus is optimized to store data that is index-based on series. It is designed for a relatively consistent number of time series and a relatively large number of samples that need to be collected from the exporters over time.

    Inversely, Prometheus is not optimized to accommodate a rapidly changing number of time series. For that reason, large bursts of memory usage can occur when monitoring is installed on clusters where many resources are being created and destroyed, especially on multi-tenant clusters.

    Reducing Memory Bursts​

    To reduce memory consumption, Prometheus can be configured to store fewer time series, by scraping fewer metrics or by attaching fewer labels to the time series. To see which series use the most memory, you can check the TSDB (time series database) status page in the Prometheus UI.

    Distributed Prometheus solutions such as Thanos and Cortex use an alternate architecture in which multiple small Prometheus instances are deployed. In the case of Thanos, the metrics from each Prometheus are aggregated into the common Thanos deployment, and then those metrics are exported to a persistent store, such as S3. This more robust architecture avoids burdening any single Prometheus instance with too many time series, while also preserving the ability to query metrics on a global level.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html index 0012d0b6d78..b6d44e83f1e 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/enable-monitoring.html @@ -5,13 +5,13 @@ Enable Monitoring | Rancher Manager - +
    Version: v2.5

    Enable Monitoring

    As an administrator or cluster owner, you can configure Rancher to deploy Prometheus to monitor your Kubernetes cluster.

    This page describes how to enable monitoring and alerting within a cluster using the new monitoring application.

    You can enable monitoring with or without SSL.

    Requirements

    • Make sure that you are allowing traffic on port 9796 for each of your nodes because Prometheus will scrape metrics from here.
    • Make sure your cluster fulfills the resource requirements. The cluster should have at least 1950Mi memory available, 2700m CPU, and 50Gi storage. A breakdown of the resource limits and requests is here.
    • When installing monitoring on an RKE cluster using RancherOS or Flatcar Linux nodes, change the etcd node certificate directory to /opt/rke/etc/kubernetes/ssl.
    • For clusters provisioned with the RKE CLI and the address is set to a hostname instead of an IP address, set rkeEtcd.clients.useLocalhost to true during the Values configuration step of the installation. The YAML snippet will look like the following:
    rkeEtcd:
      clients:
        useLocalhost: true

    Note: If you want to set up Alertmanager, Grafana or Ingress, it has to be done with the settings on the Helm chart deployment. It's problematic to create Ingress outside the deployment.

    Setting Resource Limits and Requests

    The resource requests and limits can be configured when installing rancher-monitoring. To configure Prometheus resources from the Rancher UI, click Apps & Marketplace > Monitoring in the upper left corner.

    For more information about the default limits, see this page.

    Install the Monitoring Application

    Enable Monitoring for use without SSL​

    1. In the Rancher UI, go to the cluster where you want to install monitoring and click Cluster Explorer.
    2. Click Apps.
    3. Click the rancher-monitoring app.
    4. Optional: Click Chart Options and configure alerting, Prometheus and Grafana. For help, refer to the configuration reference.
    5. Scroll to the bottom of the Helm chart README and click Install.

    Result: The monitoring app is deployed in the cattle-monitoring-system namespace.

    Enable Monitoring for use with SSL​

    1. Follow the steps on this page to create a secret in order for SSL to be used for alerts.
    • The secret should be created in the cattle-monitoring-system namespace. If it doesn't exist, create it first.
    • Add the ca, cert, and key files to the secret.
    1. In the Rancher UI, go to the cluster where you want to install monitoring and click Cluster Explorer.
    2. Click Apps.
    3. Click the rancher-monitoring app.
    4. Click Alerting.
    5. Click Additional Secrets and add the secrets created earlier.

    Result: The monitoring app is deployed in the cattle-monitoring-system namespace.

    When creating a receiver, SSL-enabled receivers such as email or webhook will have a SSL section with fields for CA File Path, Cert File Path, and Key File Path. Fill in these fields with the paths to each of ca, cert, and key. The path will be of the form /etc/alertmanager/secrets/name-of-file-in-secret.

    For example, if you created a secret with these key-value pairs:

    ca.crt=`base64-content`
    cert.pem=`base64-content`
    key.pfx=`base64-content`

    Then Cert File Path would be set to /etc/alertmanager/secrets/cert.pem.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html index d5b2fac4c34..c5c6653c41d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/migrate-to-rancher-v2.5+-monitoring.html @@ -5,14 +5,14 @@ Migrating to Rancher v2.5 Monitoring | Rancher Manager - +
    Version: v2.5

    Migrating to Rancher v2.5 Monitoring

    If you previously enabled Monitoring, Alerting, or Notifiers in Rancher before v2.5, there is no automatic upgrade path for switching to the new monitoring/alerting solution. Before deploying the new monitoring solution via Cluster Explore, you will need to disable and remove all existing custom alerts, notifiers and monitoring installations for the whole cluster and in all projects.

    Monitoring Before Rancher v2.5​

    As of v2.2.0, Rancher's Cluster Manager allowed users to enable Monitoring & Alerting V1 (both powered by Prometheus Operator) independently within a cluster.

    When Monitoring is enabled, Monitoring V1 deploys Prometheus and Grafana onto a cluster to monitor the state of processes of your cluster nodes, Kubernetes components, and software deployments and create custom dashboards to make it easy to visualize collected metrics.

    Monitoring V1 could be configured on both a cluster-level and on a project-level and would automatically scrape certain workloads deployed as Apps on the Rancher cluster.

    When Alerts or Notifiers are enabled, Alerting V1 deploys Prometheus Alertmanager and a set of Rancher controllers onto a cluster that allows users to define alerts and configure alert-based notifications via Email, Slack, PagerDuty, etc. Users can choose to create different types of alerts depending on what needs to be monitored (e.g. System Services, Resources, CIS Scans, etc.); however, PromQL Expression-based alerts can only be created if Monitoring V1 is enabled.

    Monitoring and Alerting via Cluster Explorer in Rancher 2.5​

    As of v2.5.0, Rancher's Cluster Explorer now allows users to enable Monitoring & Alerting V2 (both powered by Prometheus Operator) together within a cluster.

    Unlike in Monitoring & Alerting V1, both features are packaged in a single Helm chart found here. The behavior of this chart and configurable fields closely matches kube-prometheus-stack, a Prometheus Community Helm chart, and any deviations from the upstream chart can be found in the CHANGELOG.md maintained with the chart.

    Monitoring V2 can only be configured on the cluster level. Project-level monitoring and alerting is no longer supported.

    For more information on how to configure Monitoring & Alerting V2, see this page.

    Changes to Role-based Access Control​

    Project owners and members no longer get access to Grafana or Prometheus by default. If view-only users had access to Grafana, they would be able to see data from any namespace. For Kiali, any user can edit things they don’t own in any namespace.

    For more information about role-based access control in rancher-monitoring, refer to this page.

    Migrating from Monitoring V1 to Monitoring V2​

    While there is no automatic migration available, it is possible to manually migrate custom Grafana dashboards and alerts that were created in Monitoring V1 to Monitoring V2.

    Before you can install Monitoring V2, Monitoring V1 needs to be uninstalled completely. In order to uninstall Monitoring V1:

    • Remove all cluster and project specific alerts and alerts groups.
    • Remove all notifiers.
    • Disable all project monitoring installations under Cluster -> Project -> Tools -> Monitoring.
    • Ensure that all project-monitoring apps in all projects have been removed and are not recreated after a few minutes
    • Disable the cluster monitoring installation under Cluster -> Tools -> Monitoring.
    • Ensure that the cluster-monitoring app and the monitoring-operator app in the System project have been removed and are not recreated after a few minutes.

    RKE Template Clusters​

    To prevent V1 monitoring from being re-enabled, disable monitoring and in future RKE template revisions via modification of the RKE template yaml:

    enable_cluster_alerting: false
    enable_cluster_monitoring: false

    Migrating Grafana Dashboards​

    You can migrate any dashboard added to Grafana in Monitoring V1 to Monitoring V2. In Monitoring V1 you can export an existing dashboard like this:

    • Sign into Grafana
    • Navigate to the dashboard you want to export
    • Go to the dashboard settings
    • Copy the JSON Model

    In the JSON Model, change all datasource fields from RANCHER_MONITORING to Prometheus. You can easily do this by replacing all occurrences of "datasource": "RANCHER_MONITORING" with "datasource": "Prometheus".

    If Grafana is backed by a persistent volume, you can now import this JSON Model into the Monitoring V2 Grafana UI. It is recommended to provide the dashboard to Grafana with a ConfigMap in the cattle-dashboards namespace that has the label grafana_dashboard: "1":

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: custom-dashboard
      namespace: cattle-dashboards
      labels:
        grafana_dashboard: "1"
    data:
      custom-dashboard.json: |
        {
          ...
        }

    Once this ConfigMap is created, the dashboard will automatically be added to Grafana.

    Migrating Alerts​

    It is only possible to directly migrate expression-based alerts to Monitoring V2. Fortunately, the event-based alerts that could be set up to alert on system component, node or workload events, are already covered out-of-the-box by the alerts that are part of Monitoring V2. So it is not necessary to migrate them.

    To migrate the following expression alert

    you have to either create a PrometheusRule configuration like this in any namespace

    apiVersion: monitoring.coreos.com/v1
    kind: PrometheusRule
    metadata:
      name: custom-rules
      namespace: default
    spec:
      groups:
        - name: custom.rules
          rules:
            - alert: Custom Expression Alert
              expr: prometheus_query > 5
              for: 5m
              labels:
                severity: critical
              annotations:
                summary: "The result of prometheus_query has been larger than 5 for 5m. Current value {{ $value }}"

    or add the Prometheus Rule through the Cluster Explorer

    For more details on how to configure PrometheusRules in Monitoring V2 see Monitoring Configuration.

    Migrating Notifiers​

    There is no direct equivalent for how notifiers work in Monitoring V1. Instead you have to replicate the desired setup with Routes and Receivers in Monitoring V2.

    Migrating for RKE Template Users​

    If the cluster is managed using an RKE template, you will need to disable monitoring in future RKE template revisions to prevent legacy monitoring from being re-enabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html index 8667b4fd470..8abd110aaa5 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/set-up-monitoring-for-workloads.html @@ -5,13 +5,13 @@ Setting up Monitoring for a Workload | Rancher Manager - +
    Version: v2.5

    Setting up Monitoring for a Workload

    If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default.

    The steps for setting up monitoring for workloads depend on whether you want basic metrics such as CPU and memory for the workload, or whether you want to scrape custom metrics from the workload.

    If you only need CPU and memory time series for the workload, you don't need to deploy a ServiceMonitor or PodMonitor because the monitoring application already collects metrics data on resource usage by default. The resource usage time series data is in Prometheus's local time series database.

    Grafana shows the data in aggregate, but you can see the data for the individual workload by using a PromQL query that extracts the data for that workload. Once you have the PromQL query, you can execute the query individually in the Prometheus UI and see the time series visualized there, or you can use the query to customize a Grafana dashboard to display the workload metrics. For examples of PromQL queries for workload metrics, see this section.

    To set up custom metrics for your workload, you will need to set up an exporter and create a new ServiceMonitor custom resource to configure Prometheus to scrape metrics from your exporter.

    Display CPU and Memory Metrics for a Workload​

    By default, the monitoring application already scrapes CPU and memory.

    To get some fine-grained detail for a particular workload, you can customize a Grafana dashboard to display the metrics for a particular workload.

    Setting up Metrics Beyond CPU and Memory​

    For custom metrics, you will need to expose the metrics on your application in a format supported by Prometheus.

    Then we recommend that you should create a new ServiceMonitor custom resource. When this resource is created, the Prometheus custom resource will be automatically updated so that its scrape configuration includes the new custom metrics endpoint. Then Prometheus will begin scraping metrics from the endpoint.

    You can also create a PodMonitor to expose the custom metrics endpoint, but ServiceMonitors are more appropriate for the majority of use cases.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html index f3b4fcb169f..33590445357 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-alerting-guides/uninstall-monitoring.html @@ -5,13 +5,13 @@ Uninstall Monitoring | Rancher Manager - +
    Version: v2.5

    Uninstall Monitoring

    1. From the Cluster Explorer, click Apps & Marketplace.
    2. Click Installed Apps.
    3. Go to the cattle-monitoring-system namespace and check the boxes for rancher-monitoring-crd and rancher-monitoring.
    4. Click Delete.
    5. Confirm Delete.

    Result: rancher-monitoring is uninstalled.

    Note on Persistent Grafana Dashboards: For users who are using Monitoring V2 v9.4.203 or below, uninstalling the Monitoring chart will delete the cattle-dashboards namespace, which will delete all persisted dashboards, unless the namespace is marked with the annotation helm.sh/resource-policy: "keep". This annotation is added by default in Monitoring V2 v14.5.100+ but can be manually applied on the cattle-dashboards namespace before an uninstall if an older version of the Monitoring chart is currently installed onto your cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html index 044fb97b2c9..3881425f6c4 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/alertmanager.html @@ -5,13 +5,13 @@ Alertmanager Configuration | Rancher Manager - +
    Version: v2.5

    Alertmanager Configuration

    It is usually not necessary to directly edit the Alertmanager custom resource. For most use cases, you will only need to edit the Receivers and Routes to configure notifications.

    When Receivers and Routes are updated, the monitoring application will automatically update the Alertmanager custom resource to be consistent with those changes.

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    About the Alertmanager Custom Resource​

    By default, Rancher Monitoring deploys a single Alertmanager onto a cluster that uses a default Alertmanager Config Secret.

    You may want to edit the Alertmanager custom resource if you would like to take advantage of advanced options that are not exposed in the Rancher UI forms, such as the ability to create a routing tree structure that is more than two levels deep.

    It is also possible to create more than one Alertmanager in a cluster, which may be useful if you want to implement namespace-scoped monitoring. In this case, you should manage the Alertmanager custom resources using the same underlying Alertmanager Config Secret.

    Deeply Nested Routes​

    While the Rancher UI only supports a routing tree that is two levels deep, you can configure more deeply nested routing structures by editing the Alertmanager YAML.

    Multiple Alertmanager Replicas​

    As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret.

    This Secret should be updated or modified any time you want to:

    • Add in new notifiers or receivers
    • Change the alerts that should be sent to specific notifiers or receivers
    • Change the group of alerts that are sent out

    By default, you can either choose to supply an existing Alertmanager Config Secret (i.e. any Secret in the cattle-monitoring-system namespace) or allow Rancher Monitoring to deploy a default Alertmanager Config Secret onto your cluster.

    By default, the Alertmanager Config Secret created by Rancher will never be modified or deleted on an upgrade or uninstall of the rancher-monitoring chart. This restriction prevents users from losing or overwriting their alerting configuration when executing operations on the chart.

    For more information on what fields can be specified in the Alertmanager Config Secret, please look at the Prometheus Alertmanager docs.

    The full spec for the Alertmanager configuration file and what it takes in can be found here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html index a43d9d16d84..70debb0672d 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheus.html @@ -5,13 +5,13 @@ Prometheus Configuration | Rancher Manager - +
    Version: v2.5

    Prometheus Configuration

    It is usually not necessary to directly edit the Prometheus custom resource because the monitoring application automatically updates it based on changes to ServiceMonitors and PodMonitors.

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    About the Prometheus Custom Resource

    The Prometheus CR defines a desired Prometheus deployment. The Prometheus Operator observes the Prometheus CR. When the CR changes, the Prometheus Operator creates prometheus-rancher-monitoring-prometheus, a Prometheus deployment based on the CR configuration.

    The Prometheus CR specifies details such as rules and what Alertmanagers are connected to Prometheus. Rancher builds this CR for you.

    Monitoring V2 only supports one Prometheus per cluster. However, you might want to edit the Prometheus CR if you want to limit monitoring to certain namespaces.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html index 83fc774aafd..29f04a55a02 100644 --- a/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html +++ b/v2.5/how-to-guides/advanced-user-guides/monitoring-v2-configuration-guides/advanced-configuration/prometheusrules.html @@ -5,13 +5,13 @@ Configuring PrometheusRules | Rancher Manager - +
    Version: v2.5

    Configuring PrometheusRules

    A PrometheusRule defines a group of Prometheus alerting and/or recording rules.

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    Creating PrometheusRules in the Rancher UI​

    Available as of v2.5.4

    Prerequisite: The monitoring application needs to be installed.

    To create rule groups in the Rancher UI,

    1. Click Cluster Explorer > Monitoring > Advanced and click Prometheus Rules.
    2. Click Create.
    3. Enter a Group Name.
    4. Configure the rules. In Rancher's UI, we expect a rule group to contain either alert rules or recording rules, but not both. For help filling out the forms, refer to the configuration options below.
    5. Click Create.

    Result: Alerts can be configured to send notifications to the receiver(s).

    About the PrometheusRule Custom Resource​

    When you define a Rule (which is declared within a RuleGroup in a PrometheusRule resource), the spec of the Rule itself contains labels that are used by Alertmanager to figure out which Route should receive this Alert. For example, an Alert with the label team: front-end will be sent to all Routes that match on that label.

    Prometheus rule files are held in PrometheusRule custom resources. A PrometheusRule allows you to define one or more RuleGroups. Each RuleGroup consists of a set of Rule objects that can each represent either an alerting or a recording rule with the following fields:

    • The name of the new alert or record
    • A PromQL expression for the new alert or record
    • Labels that should be attached to the alert or record that identify it (e.g. cluster name or severity)
    • Annotations that encode any additional important pieces of information that need to be displayed on the notification for an alert (e.g. summary, description, message, runbook URL, etc.). This field is not required for recording rules.

    For more information on what fields can be specified, please look at the Prometheus Operator spec.

    Use the label selector field ruleSelector in the Prometheus object to define the rule files that you want to be mounted into Prometheus.

    For examples, refer to the Prometheus documentation on recording rules and alerting rules.

    Configuration

    Rancher v2.5.4 introduced the capability to configure PrometheusRules by filling out forms in the Rancher UI.

    Rule Group​

    FieldDescription
    Group NameThe name of the group. Must be unique within a rules file.
    Override Group IntervalDuration in seconds for how often rules in the group are evaluated.

    Alerting Rules​

    Alerting rules allow you to define alert conditions based on PromQL (Prometheus Query Language) expressions and to send notifications about firing alerts to an external service.

    FieldDescription
    Alert NameThe name of the alert. Must be a valid label value.
    Wait To Fire ForDuration in seconds. Alerts are considered firing once they have been returned for this long. Alerts which have not yet fired for long enough are considered pending.
    PromQL ExpressionThe PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and all resultant time series will become pending/firing alerts. For more information, refer to the Prometheus documentation or our example PromQL expressions.
    LabelsLabels to add or overwrite for each alert.
    SeverityWhen enabled, labels are attached to the alert or record that identify it by the severity level.
    Severity Label ValueCritical, warning, or none
    AnnotationsAnnotations are a set of informational labels that can be used to store longer additional information, such as alert descriptions or runbook links. A runbook is a set of documentation about how to handle alerts. The annotation values can be templated.

    Recording Rules​

    Recording rules allow you to precompute frequently needed or computationally expensive PromQL (Prometheus Query Language) expressions and save their result as a new set of time series.

    FieldDescription
    Time Series NameThe name of the time series to output to. Must be a valid metric name.
    PromQL ExpressionThe PromQL expression to evaluate. Prometheus will evaluate the current value of this PromQL expression on every evaluation cycle and the result will be recorded as a new set of time series with the metric name as given by 'record'. For more information about expressions, refer to the Prometheus documentation or our example PromQL expressions.
    LabelsLabels to add or overwrite before storing the result.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html index f823683490e..be4816b3b6e 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher Installed with Docker | Rancher Manager - +
    Version: v2.5

    Backing up Rancher Installed with Docker

    After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.

    Before You Start​

    During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  --volumes-from rancher-data-<DATE> -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

    In this command, <DATE> is a placeholder for the date that the data container and backup were created. 9-27-18 for example.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version of Rancher that you're creating a backup for.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped with docker ps -a. Use these commands for help anytime while creating backups.

    Creating a Backup​

    This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container.

      docker stop <RANCHER_CONTAINER_NAME>
    3. Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
      docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
    4. From the data container that you just created (rancher-data-<DATE>), create a backup tarball (rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz). Use the following command, replacing each placeholder:
      docker run  --volumes-from rancher-data-<DATE> -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher

      Step Result: A stream of commands runs on the screen.

    5. Enter the ls command to confirm that the backup tarball was created. It will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    6. Move your backup tarball to a safe location external to your Rancher Server. Then delete the rancher-data-<DATE> container from your Rancher Server.

    7. Restart Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container:

      docker start <RANCHER_CONTAINER_NAME>

    Result: A backup tarball of your Rancher Server data is created. See Restoring Backups: Docker Installs if you need to restore backup data.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html index a4f10ffc6b6..d8ecdf80456 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters.html @@ -5,13 +5,13 @@ Backing up a Cluster | Rancher Manager - +
    Version: v2.5

    Backing up a Cluster

    In the Rancher UI, etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed.

    Rancher recommends configuring recurrent etcd snapshots for all production clusters. Additionally, one-time snapshots can easily be taken as well.

    Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    How Snapshots Work

    Snapshot Components​

    When Rancher creates a snapshot, it includes three components:

    • The cluster data in etcd
    • The Kubernetes version
    • The cluster configuration in the form of the cluster.yml

    Because the Kubernetes version is now included in the snapshot, it is possible to restore a cluster to a prior Kubernetes version.

    The multiple components of the snapshot allow you to select from the following options if you need to restore a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    It's always recommended to take a new snapshot before any upgrades.

    Generating the Snapshot from etcd Nodes​

    For each etcd node in the cluster, the etcd cluster health is checked. If the node reports that the etcd cluster is healthy, a snapshot is created from it and optionally uploaded to S3.

    The snapshot is stored in /opt/rke/etcd-snapshots. If the directory is configured on the nodes as a shared mount, it will be overwritten. On S3, the snapshot will always be from the last node that uploads it, as all etcd nodes upload it and the last will remain.

    In the case when multiple etcd nodes exist, any created snapshot is created after the cluster has been health checked, so it can be considered a valid snapshot of the data in the etcd cluster.

    Snapshot Naming Conventions​

    The name of the snapshot is auto-generated. The --name option can be used to override the name of the snapshot when creating one-time snapshots with the RKE CLI.

    When Rancher creates a snapshot of an RKE cluster, the snapshot name is based on the type (whether the snapshot is manual or recurring) and the target (whether the snapshot is saved locally or uploaded to S3). The naming convention is as follows:

    • m stands for manual
    • r stands for recurring
    • l stands for local
    • s stands for S3

    Some example snapshot names are:

    • c-9dmxz-rl-8b2cx
    • c-9dmxz-ml-kr56m
    • c-9dmxz-ms-t6bjb
    • c-9dmxz-rs-8gxc8

    How Restoring from a Snapshot Works​

    On restore, the following process is used:

    1. The snapshot is retrieved from S3, if S3 is configured.
    2. The snapshot is unzipped (if zipped).
    3. One of the etcd nodes in the cluster serves that snapshot file to the other nodes.
    4. The other etcd nodes download the snapshot and validate the checksum so that they all use the same snapshot for the restore.
    5. The cluster is restored and post-restore actions will be done in the cluster.

    Configuring Recurring Snapshots

    Select how often you want recurring snapshots to be taken as well as how many snapshots to keep. The amount of time is measured in hours. With timestamped snapshots, the user has the ability to do a point-in-time recovery.

    By default, Rancher launched Kubernetes clusters are configured to take recurring snapshots (saved to local disk). To protect against local disk failure, using the S3 Target or replicating the path on disk is advised.

    During cluster provisioning or editing the cluster, the configuration for snapshots can be found in the advanced section for Cluster Options. Click on Show advanced options.

    In the Advanced Cluster Options section, there are several options available to configure:

    OptionDescriptionDefault Value
    etcd Snapshot Backup TargetSelect where you want the snapshots to be saved. Options are either local or in S3local
    Recurring etcd Snapshot EnabledEnable/Disable recurring snapshotsYes
    Recurring etcd Snapshot Creation PeriodTime in hours between recurring snapshots12 hours
    Recurring etcd Snapshot Retention CountNumber of snapshots to retain6

    One-Time Snapshots

    In addition to recurring snapshots, you may want to take a "one-time" snapshot. For example, before upgrading the Kubernetes version of a cluster it's best to backup the state of the cluster to protect against upgrade failure.

    1. In the Global view, navigate to the cluster that you want to take a one-time snapshot.

    2. Click the ⋮ > Snapshot Now.

    Result: Based on your snapshot backup target, a one-time snapshot will be taken and saved in the selected backup target.

    Snapshot Backup Targets

    Rancher supports two different backup targets:

    Local Backup Target​

    By default, the local backup target is selected. The benefits of this option is that there is no external configuration. Snapshots are automatically saved locally to the etcd nodes in the Rancher launched Kubernetes clusters in /opt/rke/etcd-snapshots. All recurring snapshots are taken at configured intervals. The downside of using the local backup target is that if there is a total disaster and all etcd nodes are lost, there is no ability to restore the cluster.

    S3 Backup Target​

    The S3 backup target allows users to configure a S3 compatible backend to store the snapshots. The primary benefit of this option is that if the cluster loses all the etcd nodes, the cluster can still be restored as the snapshots are stored externally. Rancher recommends external targets like S3 backup, however its configuration requirements do require additional effort that should be considered.

    OptionDescriptionRequired
    S3 Bucket NameS3 bucket name where backups will be stored*
    S3 RegionS3 region for the backup bucket
    S3 Region EndpointS3 regions endpoint for the backup bucket*
    S3 Access KeyS3 access key with permission to access the backup bucket*
    S3 Secret KeyS3 secret key with permission to access the backup bucket*
    Custom CA CertificateA custom certificate used to access private S3 backends

    Using a custom CA certificate for S3​

    The backup snapshot can be stored on a custom S3 backup like minio. If the S3 back end uses a self-signed or custom certificate, provide a custom certificate using the Custom CA Certificate option to connect to the S3 backend.

    IAM Support for Storing Snapshots in S3​

    The S3 backup target supports using IAM authentication to AWS API in addition to using API credentials. An IAM role gives temporary permissions that an application can use when making API calls to S3 storage. To use IAM authentication, the following requirements must be met:

    • The cluster etcd nodes must have an instance role that has read/write access to the designated backup bucket.

    • The cluster etcd nodes must have network access to the specified S3 endpoint.

    • The Rancher Server worker node(s) must have an instance role that has read/write to the designated backup bucket.

    • The Rancher Server worker node(s) must have network access to the specified S3 endpoint.

      To give an application access to S3, refer to the AWS documentation on Using an IAM Role to Grant Permissions to Applications Running on Amazon EC2 Instances.

    Viewing Available Snapshots

    The list of all available snapshots for the cluster is available in the Rancher UI.

    1. In the Global view, navigate to the cluster that you want to view snapshots.

    2. Click Tools > Snapshots from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.

    Safe Timestamps

    Snapshot files are timestamped to simplify processing the files using external tools and scripts, but in some S3 compatible backends, these timestamps were unusable.

    The option safe_timestamp is added to support compatible file names. When this flag is set to true, all special characters in the snapshot filename timestamp are replaced.

    This option is not available directly in the UI, and is only available through the Edit as Yaml interface.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html index 5470244ed1d..fd506237840 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher.html @@ -5,13 +5,13 @@ Backing up Rancher | Rancher Manager - +
    Version: v2.5

    Backing up Rancher

    In this section, you'll learn how to back up Rancher running on any Kubernetes cluster. To backup Rancher installed with Docker, refer to the instructions for single node backups.

    The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.

    Note that the rancher-backup operator version 1.x.x is for Rancher v2.5.x.

    When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different.

    Prerequisites​

    Rancher version must be v2.5.0 and up

    1. Install the rancher-backup operator​

    The backup storage location is an operator-level setting, so it needs to be configured when rancher-backup is installed or upgraded.

    Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, or they can be stored in a persistent volume.

    1. In the Rancher UI, go to the Cluster Explorer view for the local cluster.
    2. Click Apps.
    3. Click Rancher Backups.
    4. Configure the default storage location. For help, refer to the storage configuration section.

    NOTE: There are two known issues in Fleet that occur after performing a restoration using the backup-restore-operator: Fleet agents are inoperable and clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer here for workarounds.

    2. Perform a Backup​

    To perform a backup, a custom resource of type Backup must be created.

    1. In the Cluster Explorer, go to the dropdown menu in the upper left corner and click Rancher Backups.

    2. Click Backup.

    3. Create the Backup with the form, or with the YAML editor.

    4. For configuring the Backup details using the form, click Create and refer to the configuration reference and to the examples.

    5. For using the YAML editor, we can click Create > Create from YAML. Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3. The app uses the credentialSecretNamespace value to determine where to look for the S3 backup secret:

      apiVersion: resources.cattle.io/v1
      kind: Backup
      metadata:
        name: s3-recurring-backup
      spec:
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: rancher-backups
            folder: rancher
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com
        resourceSetName: rancher-resource-set
        encryptionConfigSecretName: encryptionconfig
        schedule: "@every 1h"
        retentionCount: 10

      Note: When creating the Backup resource using YAML editor, the resourceSetName must be set to rancher-resource-set

      For help configuring the Backup, refer to the configuration reference and to the examples.

      Important: The rancher-backup operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup.

    6. Click Create.

    Result: The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html index a3df1574665..45dfd7a618d 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.html @@ -5,13 +5,13 @@ Migrating Rancher to a New Cluster | Rancher Manager - +
    Version: v2.5

    Migrating Rancher to a New Cluster

    If you are migrating Rancher to a new Kubernetes cluster, you don't need to install Rancher on the new cluster first. If Rancher is restored to a new cluster with Rancher already installed, it can cause problems.

    Prerequisites​

    These instructions assume you have created a backup and you have already installed a new Kubernetes cluster where Rancher will be deployed.

    It is required to use the same hostname that was set as the server URL in the first cluster.

    Rancher version must be v2.5.0 and up

    Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes clusters such as Amazon EKS clusters. For help installing Kubernetes, refer to the documentation of the Kubernetes distribution. One of Rancher's Kubernetes distributions may also be used:

    1. Install the rancher-backup Helm chart​

    Install version 1.x.x of the rancher-backup chart. The following assumes a connected environment with access to DockerHub:

    helm repo add rancher-charts https://charts.rancher.io
    helm repo update
    helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION
    helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION

    For an **air-gapped environment**, use the option below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup-crd helm chart. ``` --set image.repository $REGISTRY/rancher/backup-restore-operator ```

    2. Restore from backup using a Restore custom resource​

    If you are using an S3 store as the backup source, and need to use your S3 credentials for restore, create a secret in this cluster using your S3 credentials. The Secret data must have two keys, accessKey and secretKey containing the s3 credentials like this:

    apiVersion: v1
    kind: Secret
    metadata:
      name: s3-creds
    type: Opaque
    stringData:
      accessKey: <Enter your base64-encoded access key>
      secretKey: <Enter your base64-encoded secret key>

    This secret can be created in any namespace, with the above example it will get created in the default namespace

    In the Restore custom resource, prune must be set to false.

    Create a Restore custom resource like the example below:

    # migrationResource.yaml
    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-migration
    spec:
      backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
      prune: false
      encryptionConfigSecretName: encryptionconfig
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: backup-test
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com

    Important: The field encryptionConfigSecretName must be set only if your backup was created with encryption enabled. Provide the name of the Secret containing the encryption config file. If you only have the encryption config file, but don't have a secret created with it in this cluster, use the following steps to create the secret:

    1. The encryption configuration file must be named encryption-provider-config.yaml, and the --from-file flag must be used to create this secret. So save your EncryptionConfiguration in a file called encryption-provider-config.yaml and run this command:

      kubectl create secret generic encryptionconfig \
        --from-file=./encryption-provider-config.yaml \
        -n cattle-resources-system

    2. Then apply the resource:

      kubectl apply -f migrationResource.yaml

    3. Install cert-manager​

    Follow the steps to install cert-manager in the documentation about installing cert-manager on Kubernetes.

    4. Bring up Rancher with Helm​

    Use the same version of Helm to install Rancher, that was used on the first cluster.

    helm install rancher rancher-latest/rancher \
      --namespace cattle-system \
      --set hostname=<same hostname as the server URL from the first Rancher server> \
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html index de7ac7670cf..572767deff2 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.html @@ -5,13 +5,13 @@ Restoring Backups—Docker Installs | Rancher Manager - +
    Version: v2.5

    Restoring Backups—Docker Installs

    If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.

    Before You Start​

    During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (<EXAMPLE>). Here's an example of a command with a placeholder:

    docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
    busybox sh -c "rm /var/lib/rancher/* -rf  && \
    tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"

    In this command, <RANCHER_CONTAINER_NAME> and <RANCHER_VERSION>-<DATE> are environment variables for your Rancher deployment.

    Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.

    Terminal docker ps Command, Displaying Where to Find <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME>

    Placeholder Reference

    PlaceholderExampleDescription
    <RANCHER_CONTAINER_TAG>v2.0.5The rancher/rancher image you pulled for initial install.
    <RANCHER_CONTAINER_NAME>festive_mestorfThe name of your Rancher container.
    <RANCHER_VERSION>v2.0.5The version number for your Rancher backup.
    <DATE>9-27-18The date that the data container or backup was created.

    You can obtain <RANCHER_CONTAINER_TAG> and <RANCHER_CONTAINER_NAME> by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: docker ps. You can also view containers that are stopped using a different command: docker ps -a. Use these commands for help anytime during while creating backups.

    Restoring Backups​

    Using a backup that you created earlier, restore Rancher to its last known healthy state.

    1. Using a remote Terminal connection, log into the node running your Rancher Server.

    2. Stop the container currently running Rancher Server. Replace <RANCHER_CONTAINER_NAME> with the name of your Rancher container:

      docker stop <RANCHER_CONTAINER_NAME>

    3. Move the backup tarball that you created during completion of Creating Backups—Docker Installs onto your Rancher Server. Change to the directory that you moved it to. Enter dir to confirm that it's there.

      If you followed the naming convention we suggested in Creating Backups—Docker Installs, it will have a name similar to rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz.

    4. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes.

      Warning! This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.

      docker run  --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
      busybox sh -c "rm /var/lib/rancher/* -rf  && \
      tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"

      Step Result: A series of commands should run.

    5. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data.

      docker start <RANCHER_CONTAINER_NAME>

    6. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html index d3a8a979f96..451e4ce8b38 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher-launched-kubernetes-clusters-from-backup.html @@ -5,13 +5,13 @@ Restoring a Cluster from Backup | Rancher Manager - +
    Version: v2.5

    Restoring a Cluster from Backup

    etcd backup and recovery for Rancher launched Kubernetes clusters can be easily performed. Snapshots of the etcd database are taken and saved either locally onto the etcd nodes or to a S3 compatible target. The advantages of configuring S3 is that if all etcd nodes are lost, your snapshot is saved remotely and can be used to restore the cluster.

    Rancher recommends enabling the ability to set up recurring snapshots of etcd, but one-time snapshots can easily be taken as well. Rancher allows restore from saved snapshots or if you don't have any snapshots, you can still restore etcd.

    Clusters can also be restored to a prior Kubernetes version and cluster configuration.

    Viewing Available Snapshots​

    The list of all available snapshots for the cluster is available.

    1. In the Global view, navigate to the cluster that you want to view snapshots.

    2. Click Tools > Snapshots from the navigation bar to view the list of saved snapshots. These snapshots include a timestamp of when they were created.

    Restoring a Cluster from a Snapshot​

    If your Kubernetes cluster is broken, you can restore the cluster from a snapshot.

    Snapshots are composed of the cluster data in etcd, the Kubernetes version, and the cluster configuration in the cluster.yml. These components allow you to select from the following options when restoring a cluster from a snapshot:

    • Restore just the etcd contents: This restore is similar to restoring to snapshots in Rancher before v2.4.0.
    • Restore etcd and Kubernetes version: This option should be used if a Kubernetes upgrade is the reason that your cluster is failing, and you haven't made any cluster configuration changes.
    • Restore etcd, Kubernetes versions and cluster configuration: This option should be used if you changed both the Kubernetes version and cluster configuration when upgrading.

    When rolling back to a prior Kubernetes version, the upgrade strategy options are ignored. Worker nodes are not cordoned or drained before being reverted to the older Kubernetes version, so that an unhealthy cluster can be more quickly restored to a healthy state.

    Prerequisite: To restore snapshots from S3, the cluster needs to be configured to take recurring snapshots on S3.

    1. In the Global view, navigate to the cluster that you want to restore from a snapshots.

    2. Click the ⋮ > Restore Snapshot.

    3. Select the snapshot that you want to use for restoring your cluster from the dropdown of available snapshots.

    4. In the Restoration Type field, choose one of the restore options described above.

    5. Click Save.

    Result: The cluster will go into updating state and the process of restoring the etcd nodes from the snapshot will start. The cluster is restored when it returns to an active state.

    Recovering etcd without a Snapshot​

    If the group of etcd nodes loses quorum, the Kubernetes cluster will report a failure because no operations, e.g. deploying workloads, can be executed in the Kubernetes cluster. The cluster should have three etcd nodes to prevent a loss of quorum. If you want to recover your set of etcd nodes, follow these instructions:

    1. Keep only one etcd node in the cluster by removing all other etcd nodes.

    2. On the single remaining etcd node, run the following command:

      $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock assaflavie/runlike etcd

      This command outputs the running command for etcd, save this command to use later.

    3. Stop the etcd container that you launched in the previous step and rename it to etcd-old.

      $ docker stop etcd
      $ docker rename etcd etcd-old

    4. Take the saved command from Step 2 and revise it:

      • If you originally had more than 1 etcd node, then you need to change --initial-cluster to only contain the node that remains.
      • Add --force-new-cluster to the end of the command.

    5. Run the revised command.

    6. After the single nodes is up and running, Rancher recommends adding additional etcd nodes to your cluster. If you have a custom cluster and you want to reuse an old node, you are required to clean up the nodes before attempting to add them back into a cluster.

    Enabling Snapshot Features for Clusters Created Before Rancher v2.2.0

    If you have any Rancher launched Kubernetes clusters that were created before v2.2.0, after upgrading Rancher, you must edit the cluster and save it, in order to enable the updated snapshot features. Even if you were already creating snapshots before v2.2.0, you must do this step as the older snapshots will not be available to use to back up and restore etcd through the UI.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html index 8b6cc712115..936a317046c 100644 --- a/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.html @@ -5,13 +5,13 @@ Restoring Rancher | Rancher Manager - +
    Version: v2.5

    Restoring Rancher

    A restore is performed by creating a Restore custom resource.

    Important

    • Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to migrate rancher.
    • While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore.
    • When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made.

    Create the Restore Custom Resource​

    1. In the Cluster Explorer, go to the dropdown menu in the upper left corner and click Rancher Backups.

    2. Click Restore.

    3. Create the Restore with the form, or with YAML. For creating the Restore resource using form, refer to the configuration reference and to the examples.

    4. For using the YAML editor, we can click Create > Create from YAML. Enter the Restore YAML.

      apiVersion: resources.cattle.io/v1
      kind: Restore
      metadata:
        name: restore-migration
      spec:
        backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
        encryptionConfigSecretName: encryptionconfig
        storageLocation:
          s3:
            credentialSecretName: s3-creds
            credentialSecretNamespace: default
            bucketName: rancher-backups
            folder: rancher
            region: us-west-2
            endpoint: s3.us-west-2.amazonaws.com

      For help configuring the Restore, refer to the configuration reference and to the examples.

    5. Click Create.

    Result: The rancher-operator scales down the rancher deployment during restore, and scales it back up once the restore completes. The resources are restored in this order:

    1. Custom Resource Definitions (CRDs)
    2. Cluster-scoped resources
    3. Namespaced resources

    Logs​

    To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:

    kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f

    Cleanup​

    If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores.

    Known Issues​

    In some cases, after restoring the backup, Rancher logs will show errors similar to the following:

    2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing

    This happens because one of the resources that was just restored has finalizers but the related resources have been deleted so the handler cannot find it.

    To eliminate the errors, we need to find and delete the resource that causes the error. See more information here

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html b/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html index 482129e86e7..4d7be69e24f 100644 --- a/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html +++ b/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/fleet.html @@ -5,14 +5,14 @@ Fleet - GitOps at Scale | Rancher Manager - +
    Version: v2.5

    Fleet - GitOps at Scale

    Available as of Rancher v2.5

    Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It's also lightweight enough that it works great for a single cluster too, but it really shines when you get to a large scale. By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.

    Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.

    Architecture​

    For information about how Fleet works, see this page.

    Accessing Fleet in the Rancher UI​

    Fleet comes preinstalled in Rancher v2.5. Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following gitops practice. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer here.

    Follow the steps below to access Continuous Delivery in the Rancher UI:

    1. Click Cluster Explorer in the Rancher UI.

    2. In the top left dropdown menu, click Cluster Explorer > Continuous Delivery.

    3. Select your namespace at the top of the menu, noting the following:

      • By default,fleet-default is selected which includes all downstream clusters that are registered through Rancher.
      • You may switch to fleet-local, which only contains the local cluster, or you may create your own workspace to which you may assign and move clusters.
      • You can then manage clusters by clicking on Clusters on the left navigation bar.

    4. Click on Gitrepos on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.

    5. Select your git repository and target clusters/cluster group. You can also create the cluster group in the UI by clicking on Cluster Groups from the left navigation bar.

    6. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.

    Windows Support​

    Available as of v2.5.6

    For details on support for clusters with Windows nodes, see this page.

    GitHub Repository​

    The Fleet Helm charts are available here.

    Using Fleet Behind a Proxy​

    Available as of v2.5.8

    For details on using Fleet behind a proxy, see this page.

    Helm Chart Dependencies​

    In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run helm install, your installation will fail because the dependencies will be missing.

    The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run helm dependencies update $chart OR run helm dependencies build $chart locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters.

    Troubleshooting​

    • Known Issue: Fleet becomes inoperable after a restore using the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround: 

        1. Find the two service account tokens listed in the fleet-controller and the fleet-controller-bootstrap service accounts. These are under the fleet-system namespace of the local cluster. <br/>
        2. Remove the non-existent token secret. Doing so allows for only one entry to be present for the service account token secret that actually exists. <br/>
        3. Delete the fleet-controller Pod in the fleet-system namespace to reschedule. <br/>
        4. After the service account token issue is resolved, you can force redeployment of the fleet-agents. In the Rancher UI, go to **☰ > Cluster Management**, click on **Clusters** page, then click **Force Update**. <br/>
        5. If the fleet-agent bundles remain in a `Modified` state after Step 4, update the field `spec.forceSyncGeneration` for the fleet-agent bundle to force re-creation.

    • Known Issue: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround:
      By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs here.

    Documentation​

    The Fleet documentation is at https://fleet.rancher.io/.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html b/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html index 854342260c5..686a8806b84 100644 --- a/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html +++ b/v2.5/how-to-guides/new-user-guides/deploy-apps-across-clusters/multi-cluster-apps.html @@ -5,14 +5,14 @@ Multi-cluster Apps | Rancher Manager - +
    Version: v2.5

    Multi-cluster Apps

    As of Rancher v2.5, we now recommend using Fleet for deploying apps across clusters.

    Typically, most applications are deployed on a single Kubernetes cluster, but there will be times you might want to deploy multiple copies of the same application across different clusters and/or projects. In Rancher, a multi-cluster application, is an application deployed using a Helm chart across multiple clusters. With the ability to deploy the same application across multiple clusters, it avoids the repetition of the same action on each cluster, which could introduce user error during application configuration. With multi-cluster applications, you can customize to have the same configuration across all projects/clusters as well as have the ability to change the configuration based on your target project. Since multi-cluster application is considered a single application, it's easy to manage and maintain this application.

    Any Helm charts from a global catalog can be used to deploy and manage multi-cluster applications.

    After creating a multi-cluster application, you can program a global DNS entry to make it easier to access the application.

    Prerequisites​

    To create a multi-cluster app in Rancher, you must have at least one of the following permissions:

    • A project-member role in the target cluster(s), which gives you the ability to create, read, update, and delete the workloads
    • A cluster owner role for the clusters(s) that include the target project(s)

    Launching a Multi-Cluster App​

    1. From the Global view, choose Apps in the navigation bar. Click Launch.

    2. Find the application that you want to launch, and then click View Details.

    3. (Optional) Review the detailed descriptions, which are derived from the Helm chart's README.

    4. Under Configuration Options enter a Name for the multi-cluster application. By default, this name is also used to create a Kubernetes namespace in each target project for the multi-cluster application. The namespace is named as <MULTI-CLUSTER_APPLICATION_NAME>-<PROJECT_ID>.

    5. Select a Template Version.

    6. Complete the multi-cluster applications specific configuration options as well as the application configuration options.

    7. Select the Members who can interact with the multi-cluster application.

    8. Add any custom application configuration answers that would change the configuration for specific project(s) from the default application configuration answers.

    9. Review the files in the Preview section. When you're satisfied, click Launch.

    Result: Your application is deployed to your chosen namespace. You can view the application status from the project's:

    Multi-cluster App Configuration Options​

    Rancher has divided the configuration option for the multi-cluster application into several sections.

    Targets​

    In the Targets section, select the projects that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on -.

    Upgrades​

    In the Upgrades section, select the upgrade strategy to use, when you decide to upgrade your application.

    • Rolling Update (batched): When selecting this upgrade strategy, the number of applications upgraded at a time is based on the selected Batch size and the Interval specifies how many seconds to wait before starting the next batch of updates.

    • Upgrade all apps simultaneously: When selecting this upgrade strategy, all applications across all projects will be upgraded at the same time.

    Roles​

    In the Roles section, you define the role of the multi-cluster application. Typically, when a user launches catalog applications, that specific user's permissions are used for creation of all workloads/resources that is required by the app.

    For multi-cluster applications, the application is deployed by a system user and is assigned as the creator of all underlying resources. A system user is used instead of the actual user due to the fact that the actual user could be removed from one of the target projects. If the actual user was removed from one of the projects, then that user would no longer be able to manage the application for the other projects.

    Rancher will let you select from two options for Roles, Project and Cluster. Rancher will allow creation using any of these roles based on the user's permissions.

    • Project - This is the equivalent of a project member. If you select this role, Rancher will check that in all the target projects, the user has minimally the project member role. While the user might not be explicitly granted the project member role, if the user is an administrator, a cluster owner, or a project owner, then the user is considered to have the appropriate level of permissions.

    • Cluster - This is the equivalent of a cluster owner. If you select this role, Rancher will check that in all the target projects, the user has minimally the cluster owner role. While the user might not be explicitly granted the cluster owner role, if the user is an administrator, then the user is considered to have the appropriate level of permissions.

    When launching the application, Rancher will confirm if you have these permissions in the target projects before launching the application.

    Note: There are some applications like Grafana or Datadog that require access to specific cluster-scoped resources. These applications will require the Cluster role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles.

    Application Configuration Options​

    For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in Using Helm: The format and limitations of –set, as Rancher passes them as --set flags to Helm.

    For example, when entering an answer that includes two values separated by a comma (i.e. abc, bcd), it is required to wrap the values with double quotes (i.e., "abc, bcd").

    Using a questions.yml file​

    If the Helm chart that you are deploying contains a questions.yml file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.

    Key Value Pairs for Native Helm Charts​

    For native Helm charts (i.e., charts from the Helm Stable or Helm Incubator catalogs or a custom Helm chart repository, answers are provided as key value pairs in the Answers section. These answers are used to override the default values.

    Members​

    By default, multi-cluster applications can only be managed by the user who created it. In the Members section, other users can be added so that they can also help manage or view the multi-cluster application.

    1. Find the user that you want to add by typing in the member's name in the Member search box.

    2. Select the Access Type for that member. There are three access types for a multi-cluster project, but due to how the permissions of a multi-cluster application are launched, please read carefully to understand what these access types mean.

      • Owner: This access type can manage any configuration part of the multi-cluster application including the template version, the [multi-cluster applications specific configuration options](#Multi-cluster App Configuration Options), the application specific configuration options, the members who can interact with the multi-cluster application and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any owner of the multi-cluster application can manage/remove applications in target projects without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Member: This access type can only modify the template version, the application specific configuration options and the custom application configuration answers. Since a multi-cluster application is created with a different set of permissions from the user, any member of the multi-cluster application can modify the application without explicitly having access to these project(s). Only trusted users should be provided with this access type.

      • Read-only: This access type cannot modify any configuration option for the multi-cluster application. Users can only view these applications.

      Note: Please ensure only trusted users are given Owner or Member access as they will automatically be able to manage applications created for this multi-cluster application in target projects they might not have direct access to.

    Overriding Application Configuration Options for Specific Projects​

    The ability to use the same configuration to deploy the same application across multiple clusters/projects is one of the main benefits of multi-cluster applications. There might be a specific project that requires a slightly different configuration option, but you want to manage that application with all the other matching applications. Instead of creating a brand new application, you can override specific application specific configuration options for specific projects.

    1. In the Answer Overrides section, click Add Override.

    2. For each override, you can select the following:

      • Scope: Select which target projects you want to override the answer in the configuration option.

      • Question: Select which question you want to override.

      • Answer: Enter the answer that you want to be used instead.

    Upgrading Multi-Cluster App Roles and Projects​

    • Changing Roles on an existing Multi-Cluster app The creator and any users added with the access-type "owner" to a multi-cluster app, can upgrade its Roles. When adding a new Role, we check if the user has that exact role in all current target projects. These checks allow the same relaxations for global admins, cluster owners and project-owners as described in the installation section for the field Roles.

    • Adding/Removing target projects

    1. The creator and any users added with access-type "owner" to a multi-cluster app, can add or remove its target projects. When adding a new project, we check if the caller of this request has all Roles defined on multi-cluster app, in the new projects they want to add. The roles checks are again relaxed for global admins, cluster-owners and project-owners.
    2. We do not do these membership checks when removing target projects. This is because the caller's permissions could have with respect to the target project, or the project could have been deleted and hence the caller wants to remove it from targets list.

    Multi-Cluster Application Management​

    One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back.

    1. From the Global view, choose Apps in the navigation bar.

    2. Choose the multi-cluster application you want to take one of these actions on and click the ⋮. Select one of the following options:

      • Clone: Creates another multi-cluster application with the same configuration. By using this option, you can easily duplicate a multi-cluster application.
      • Upgrade: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the upgrade strategy can be modified if you have the correct access type.
      • Rollback: Rollback your application to a specific version. If after an upgrade, there are issues for your multi-cluster application for one or more of your targets, Rancher has stored up to 10 versions of the multi-cluster application. Rolling back a multi-cluster application reverts the application for all target clusters and projects, not just the targets(s) affected by the upgrade issue.

    Deleting a Multi-Cluster Application​

    1. From the Global view, choose Apps in the navigation bar.

    2. Choose the multi-cluster application you want to delete and click the ⋮ > Delete. When deleting the multi-cluster application, all applications and namespaces are deleted in all of the target projects.

      Note: The applications in the target projects, that are created for a multi-cluster application, cannot be deleted individually. The applications can only be deleted when the multi-cluster application is deleted.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html index aa7bab1c7c8..aaced1afd47 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/amazon-elb-load-balancer.html @@ -5,13 +5,13 @@ Setting up Amazon ELB Network Load Balancer | Rancher Manager - +
    Version: v2.5

    Setting up Amazon ELB Network Load Balancer

    This how-to guide describes how to set up a Network Load Balancer (NLB) in Amazon's EC2 service that will direct traffic to multiple instances on EC2.

    These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required.

    This tutorial is about one possible way to set up your load balancer, not the only way. Other types of load balancers, such as a Classic Load Balancer or Application Load Balancer, could also direct traffic to the Rancher server nodes.

    Rancher only supports using the Amazon NLB when terminating traffic in tcp mode for port 443 rather than tls mode. This is due to the fact that the NLB does not inject the correct headers into requests when terminated at the NLB. This means that if you want to use certificates managed by the Amazon Certificate Manager (ACM), you should use an ALB.

    Setting up the Load Balancer

    Configuring an Amazon NLB is a multistage process:

    1. Create Target Groups
    2. Register Targets
    3. Create Your NLB
    4. Add listener to NLB for TCP port 80

    Requirements

    These instructions assume you have already created Linux instances in EC2. The load balancer will direct traffic to these nodes.

    1. Create Target Groups

    Begin by creating two target groups for the TCP protocol, one with TCP port 443 and one regarding TCP port 80 (providing redirect to TCP port 443). You'll add your Linux nodes to these groups.

    Your first NLB configuration step is to create two target groups. Technically, only port 443 is needed to access Rancher, but it's convenient to add a listener for port 80, because traffic to port 80 will be automatically redirected to port 443.

    Regardless of whether an NGINX Ingress or Traefik Ingress controller is used, the Ingress should redirect traffic from port 80 to port 443.

    1. Log into the Amazon AWS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. Select Services and choose EC2, find the section Load Balancing and open Target Groups.
    3. Click Create target group to create the first target group, regarding TCP port 443.

    Note: Health checks are handled differently based on the Ingress. For details, refer to this section.

    Target Group (TCP port 443)​

    Configure the first target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-443
    Target typeinstance
    ProtocolTCP
    Port443
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Portoverride,80
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    Click Create target group to create the second target group, regarding TCP port 80.

    Target Group (TCP port 80)​

    Configure the second target group according to the table below.

    OptionSetting
    Target Group Namerancher-tcp-80
    Target typeinstance
    ProtocolTCP
    Port80
    VPCChoose your VPC

    Health check settings:

    OptionSetting
    ProtocolTCP
    Porttraffic port
    Healthy threshold3
    Unhealthy threshold3
    Timeout6 seconds
    Interval10 seconds

    2. Register Targets

    Next, add your Linux nodes to both target groups.

    Select the target group named rancher-tcp-443, click the tab Targets and choose Edit.

    Select the instances (Linux nodes) you want to add, and click Add to registered.

    Screenshot Add targets to target group TCP port 443

    Screenshot Added targets to target group TCP port 443

    When the instances are added, click Save on the bottom right of the screen.

    Repeat those steps, replacing rancher-tcp-443 with rancher-tcp-80. The same instances need to be added as targets to this target group.

    3. Create Your NLB

    Use Amazon's Wizard to create a Network Load Balancer. As part of this process, you'll add the target groups you created in 1. Create Target Groups.

    1. From your web browser, navigate to the Amazon EC2 Console.

    2. From the navigation pane, choose LOAD BALANCING > Load Balancers.

    3. Click Create Load Balancer.

    4. Choose Network Load Balancer and click Create. Then complete each form.

    Step 1: Configure Load Balancer​

    Set the following fields in the form:

    • Name: rancher
    • Scheme: internal or internet-facing. The scheme that you choose for your NLB is dependent on the configuration of your instances and VPC. If your instances do not have public IPs associated with them, or you will only be accessing Rancher internally, you should set your NLB Scheme to internal rather than internet-facing.
    • Listeners: The Load Balancer Protocol should be TCP and the corresponding Load Balancer Port should be set to 443.
    • Availability Zones: Select Your VPC and Availability Zones.

    Step 2: Configure Routing​

    1. From the Target Group drop-down, choose Existing target group.
    2. From the Name drop-down, choose rancher-tcp-443.
    3. Open Advanced health check settings, and configure Interval to 10 seconds.

    Step 3: Register Targets​

    Since you registered your targets earlier, all you have to do is click Next: Review.

    Step 4: Review​

    Look over the load balancer details and click Create when you're satisfied.

    After AWS creates the NLB, click Close.

    4. Add listener to NLB for TCP port 80

    1. Select your newly created NLB and select the Listeners tab.

    2. Click Add listener.

    3. Use TCP:80 as Protocol : Port

    4. Click Add action and choose Forward to...

    5. From the Forward to drop-down, choose rancher-tcp-80.

    6. Click Save in the top right of the screen.

    Health Check Paths for NGINX Ingress and Traefik Ingresses

    K3s and RKE Kubernetes clusters handle health checks differently because they use different Ingresses by default.

    For RKE Kubernetes clusters, NGINX Ingress is used by default, whereas for K3s Kubernetes clusters, Traefik is the default Ingress.

    • Traefik: The health check path is /ping. By default /ping is always matched (regardless of Host), and a response from Traefik itself is always served.
    • NGINX Ingress: The default backend of the NGINX Ingress controller has a /healthz endpoint. By default /healthz is always matched (regardless of Host), and a response from ingress-nginx itself is always served.

    To simulate an accurate health check, it is a best practice to use the Host header (Rancher hostname) combined with /ping or /healthz (for K3s or for RKE clusters, respectively) wherever possible, to get a response from the Rancher Pods, not the Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html index 5425f9c0836..3bba4e5eba8 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-k3s-kubernetes-cluster.html @@ -5,14 +5,14 @@ Set up Infrastructure for a High Availability K3s Kubernetes Cluster | Rancher Manager - +
    Version: v2.5

    Set up Infrastructure for a High Availability K3s Kubernetes Cluster

    This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.

    The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a K3s Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.

    For more information about each installation option, refer to this page.

    Note: These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability K3s cluster, we recommend setting up the following infrastructure:

    • Two Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • An external database to store the cluster data. We recommend MySQL.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up External Datastore​

    The ability to run Kubernetes using a datastore other than etcd sets K3s apart from other Kubernetes distributions. This feature provides flexibility to Kubernetes operators. The available options allow you to select a datastore that best fits your use case.

    For a high-availability K3s installation, you will need to set a MySQL external database. Rancher has been tested on K3s Kubernetes clusters using MySQL version 5.7 as the datastore.

    When you install Kubernetes using the K3s installation script, you will pass in details for K3s to connect to the database.

    For an example of one way to set up the MySQL database, refer to this tutorial for setting up MySQL on Amazon's RDS service.

    For the complete list of options that are available for configuring a K3s cluster datastore, refer to the K3s documentation.

    3. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on both nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the K3s tool will deploy a Traefik Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. The Traefik Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html index 26e46dbc170..f7c904df9a9 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke1-kubernetes-cluster.html @@ -5,14 +5,14 @@ Set up Infrastructure for a High Availability RKE Kubernetes Cluster | Rancher Manager - +
    Version: v2.5

    Set up Infrastructure for a High Availability RKE Kubernetes Cluster

    This tutorial is intended to help you create a high-availability RKE cluster that can be used to install a Rancher server.

    Note: These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability RKE cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in an infrastructure provider such as Amazon's EC2, Google Compute Engine, or vSphere.
    • A load balancer to direct front-end traffic to the three nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    These nodes must be in the same region/data center. You may place these servers in separate availability zones.

    Why three nodes?​

    In an RKE cluster, Rancher server data is stored on etcd. This etcd database runs on all three nodes.

    The etcd database requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can suffer from split brain, requiring the cluster to be restored from backup. If one of the three etcd nodes fails, the two remaining nodes can elect a leader because they have the majority of the total number of etcd nodes.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on any of the three nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE tool will deploy an NGINX Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the NGINX Ingress controller to listen for traffic destined for the Rancher hostname. The NGINX Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    3. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the LB IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html index 1fb0353ad5b..5682b3bdb14 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/ha-rke2-kubernetes-cluster.html @@ -5,14 +5,14 @@ Set up Infrastructure for a High Availability RKE2 Kubernetes Cluster | Rancher Manager - +
    Version: v2.5

    Set up Infrastructure for a High Availability RKE2 Kubernetes Cluster

    This tutorial is intended to help you provision the underlying infrastructure for a Rancher management server.

    The recommended infrastructure for the Rancher-only Kubernetes cluster differs depending on whether Rancher will be installed on a RKE2 Kubernetes cluster, an RKE Kubernetes cluster, or a single Docker container.

    Note: These nodes must be in the same region. You may place these servers in separate availability zones (datacenter).

    To install the Rancher management server on a high-availability RKE2 cluster, we recommend setting up the following infrastructure:

    • Three Linux nodes, typically virtual machines, in the infrastructure provider of your choice.
    • A load balancer to direct traffic to the two nodes.
    • A DNS record to map a URL to the load balancer. This will become the Rancher server URL, and downstream Kubernetes clusters will need to reach it.

    1. Set up Linux Nodes​

    Make sure that your nodes fulfill the general installation requirements for OS, container runtime, hardware, and networking.

    For an example of one way to set up Linux nodes, refer to this tutorial for setting up nodes as instances in Amazon EC2.

    2. Set up the Load Balancer​

    You will also need to set up a load balancer to direct traffic to the Rancher replica on all nodes. That will prevent an outage of any single node from taking down communications to the Rancher management server.

    When Kubernetes gets set up in a later step, the RKE2 tool will deploy an Nginx Ingress controller. This controller will listen on ports 80 and 443 of the worker nodes, answering traffic destined for specific hostnames.

    When Rancher is installed (also in a later step), the Rancher system creates an Ingress resource. That Ingress tells the Nginx Ingress controller to listen for traffic destined for the Rancher hostname. The Nginx Ingress controller, when receiving traffic destined for the Rancher hostname, will forward that traffic to the running Rancher pods in the cluster.

    For your implementation, consider if you want or need to use a Layer-4 or Layer-7 load balancer:

    • A layer-4 load balancer is the simpler of the two choices, in which you are forwarding TCP traffic to your nodes. We recommend configuring your load balancer as a Layer 4 balancer, forwarding traffic to ports TCP/80 and TCP/443 to the Rancher management cluster nodes. The Ingress controller on the cluster will redirect HTTP traffic to HTTPS and terminate SSL/TLS on port TCP/443. The Ingress controller will forward traffic to port TCP/80 to the Ingress pod in the Rancher deployment.
    • A layer-7 load balancer is a bit more complicated but can offer features that you may want. For instance, a layer-7 load balancer is capable of handling TLS termination at the load balancer, as opposed to Rancher doing TLS termination itself. This can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with. If you decide to terminate the SSL/TLS traffic on a layer-7 load balancer, you will need to use the --set tls=external option when installing Rancher in a later step. For more information, refer to the Rancher Helm chart options.

    For an example showing how to set up an NGINX load balancer, refer to this page.

    For a how-to guide for setting up an Amazon ELB Network Load Balancer, refer to this page.

    Important: Do not use this load balancer (i.e, the local cluster Ingress) to load balance applications other than Rancher following installation. Sharing this Ingress with other applications may result in websocket errors to Rancher following Ingress configuration reloads for other apps. We recommend dedicating the local cluster to Rancher and no other applications.

    4. Set up the DNS Record​

    Once you have set up your load balancer, you will need to create a DNS record to send traffic to this load balancer.

    Depending on your environment, this may be an A record pointing to the load balancer IP, or it may be a CNAME pointing to the load balancer hostname. In either case, make sure this record is the hostname that you intend Rancher to respond on.

    You will need to specify this hostname in a later step when you install Rancher, and it is not possible to change it later. Make sure that your decision is a final one.

    For a how-to guide for setting up a DNS record to route domain traffic to an Amazon ELB load balancer, refer to the official AWS documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html index cd7a114a7eb..6bbee2d3ac0 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/mysql-database-in-amazon-rds.html @@ -5,13 +5,13 @@ Setting up a MySQL Database in Amazon RDS | Rancher Manager - +
    Version: v2.5

    Setting up a MySQL Database in Amazon RDS

    This tutorial describes how to set up a MySQL database in Amazon's RDS.

    This database can later be used as an external datastore for a high-availability K3s Kubernetes cluster.

    1. Log into the Amazon AWS RDS Console to get started. Make sure to select the Region where your EC2 instances (Linux nodes) are created.
    2. In the left panel, click Databases.
    3. Click Create database.
    4. In the Engine type section, click MySQL.
    5. In the Version section, choose MySQL 5.7.22.
    6. In Settings section, under Credentials Settings, enter a master password for the admin master username. Confirm the password.
    7. Expand the Additional configuration section. In the Initial database name field, enter a name. The name can have only letters, numbers, and underscores. This name will be used to connect to the database.
    8. Click Create database.

    You'll need to capture the following information about the new database so that the K3s Kubernetes cluster can connect to it.

    To see this information in the Amazon RDS console, click Databases, and click the name of the database that you created.

    • Username: Use the admin username.
    • Password: Use the admin password.
    • Hostname: Use the Endpoint as the hostname. The endpoint is available in the Connectivity & security section.
    • Port: The port should be 3306 by default. You can confirm it in the Connectivity & security section.
    • Database name: Confirm the name by going to the Configuration tab. The name is listed under DB name.

    This information will be used to connect to the database in the following format:

    mysql://username:password@tcp(hostname:3306)/database-name

    For more information on configuring the datastore for K3s, refer to the K3s documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html index 46a153fc790..bafabd34ab3 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nginx-load-balancer.html @@ -5,13 +5,13 @@ Setting up an NGINX Load Balancer | Rancher Manager - +
    Version: v2.5

    Setting up an NGINX Load Balancer

    NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes.

    In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX.

    One caveat: do not use one of your Rancher nodes as the load balancer.

    These examples show the load balancer being configured to direct traffic to three Rancher server nodes. If Rancher is installed on an RKE Kubernetes cluster, three nodes are required. If Rancher is installed on a K3s Kubernetes cluster, only two nodes are required.

    Install NGINX​

    Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are 1.14 and 1.15. For help installing NGINX, refer to their install documentation.

    The stream module is required, which is present when using the official NGINX packages. Please refer to your OS documentation on how to install and enable the NGINX stream module on your operating system.

    Create NGINX Configuration​

    After installing NGINX, you need to update the NGINX configuration file, nginx.conf, with the IP addresses for your nodes.

    1. Copy and paste the code sample below into your favorite text editor. Save it as nginx.conf.

    2. From nginx.conf, replace both occurrences (port 80 and port 443) of <IP_NODE_1>, <IP_NODE_2>, and <IP_NODE_3> with the IPs of your nodes.

      Note: See NGINX Documentation: TCP and UDP Load Balancing for all configuration options.

      Example NGINX config
      worker_processes 4;
      worker_rlimit_nofile 40000;

      events {
          worker_connections 8192;
      }

      stream {
          upstream rancher_servers_http {
              least_conn;
              server <IP_NODE_1>:80 max_fails=3 fail_timeout=5s;
              server <IP_NODE_2>:80 max_fails=3 fail_timeout=5s;
              server <IP_NODE_3>:80 max_fails=3 fail_timeout=5s;
          }
          server {
              listen 80;
              proxy_pass rancher_servers_http;
          }

          upstream rancher_servers_https {
              least_conn;
              server <IP_NODE_1>:443 max_fails=3 fail_timeout=5s;
              server <IP_NODE_2>:443 max_fails=3 fail_timeout=5s;
              server <IP_NODE_3>:443 max_fails=3 fail_timeout=5s;
          }
          server {
              listen     443;
              proxy_pass rancher_servers_https;
          }

      }

    1. Save nginx.conf to your load balancer at the following path: /etc/nginx/nginx.conf.

    2. Load the updates to your NGINX configuration by running the following command:

      # nginx -s reload

    Option - Run NGINX as Docker container​

    Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited Example NGINX config as /etc/nginx.conf and run the following command to launch the NGINX container:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /etc/nginx.conf:/etc/nginx/nginx.conf \
      nginx:1.14
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html index 2c79fadac91..6e9ee47641e 100644 --- a/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html +++ b/v2.5/how-to-guides/new-user-guides/infrastructure-setup/nodes-in-amazon-ec2.html @@ -5,13 +5,13 @@ Setting up Nodes in Amazon EC2 | Rancher Manager - +
    Version: v2.5

    Setting up Nodes in Amazon EC2

    In this tutorial, you will learn one way to set up Linux nodes for the Rancher management server. These nodes will fulfill the node requirements for OS, Docker, hardware, and networking.

    If the Rancher server will be installed on an RKE Kubernetes cluster, you should provision three instances.

    If the Rancher server will be installed on a K3s Kubernetes cluster, you only need to provision two instances.

    If the Rancher server is installed in a single Docker container, you only need one instance.

    1. Optional Preparation​

    • Create IAM role: To allow Rancher to manipulate AWS resources, such as provisioning new storage or new nodes, you will need to configure Amazon as a cloud provider. There are several things you'll need to do to set up the cloud provider on EC2, but part of this process is setting up an IAM role for the Rancher server nodes. For the full details on setting up the cloud provider, refer to this page.
    • Create security group: We also recommend setting up a security group for the Rancher nodes that complies with the port requirements for Rancher nodes.

    2. Provision Instances​

    1. Log into the Amazon AWS EC2 Console to get started. Make sure to take note of the Region where your EC2 instances (Linux nodes) are created, because all of the infrastructure for the Rancher management server should be in the same region.
    2. In the left panel, click Instances.
    3. Click Launch Instance.
    4. In the section called Step 1: Choose an Amazon Machine Image (AMI), we will use Ubuntu 18.04 as the Linux OS, using ami-0d1cd67c26f5fca19 (64-bit x86). Go to the Ubuntu AMI and click Select.
    5. In the Step 2: Choose an Instance Type section, select the t2.medium type.
    6. Click Next: Configure Instance Details.
    7. In the Number of instances field, enter the number of instances. A high-availability K3s cluster requires only two instances, while a high-availability RKE cluster requires three instances.
    8. Optional: If you created an IAM role for Rancher to manipulate AWS resources, select the new IAM role in the IAM role field.
    9. Click Next: Add Storage, Next: Add Tags, and Next: Configure Security Group.
    10. In Step 6: Configure Security Group, select a security group that complies with the port requirements for Rancher nodes.
    11. Click Review and Launch.
    12. Click Launch.
    13. Choose a new or existing key pair that you will use to connect to your instance later. If you are using an existing key pair, make sure you already have access to the private key.
    14. Click Launch Instances.

    Result: You have created Rancher nodes that satisfy the requirements for OS, hardware, and networking.

    Note: If the nodes are being used for an RKE Kubernetes cluster, install Docker on each node in the next step. For a K3s Kubernetes cluster, the nodes are now ready to install K3s.

    3. Install Docker and Create User for RKE Kubernetes Cluster Nodes​

    1. From the AWS EC2 console, click Instances in the left panel.
    2. Go to the instance that you want to install Docker on. Select the instance and click Actions > Connect.
    3. Connect to the instance by following the instructions on the screen that appears. Copy the Public DNS of the instance. An example command to SSH into the instance is as follows:
    sudo ssh -i [path-to-private-key] ubuntu@[public-DNS-of-instance]
    1. Run the following command on the instance to install Docker with one of Rancher's installation scripts:
    curl https://releases.rancher.com/install-docker/18.09.sh | sh
    1. When you are connected to the instance, run the following command on the instance to create a user:
    sudo usermod -aG docker ubuntu
    1. Repeat these steps so that Docker is installed on each node that will eventually run the Rancher management server.

    To find out whether a script is available for installing a certain Docker version, refer to this GitHub repository, which contains all of Rancher’s Docker installation scripts.

    Result: You have set up Rancher server nodes that fulfill all the node requirements for OS, Docker, hardware and networking.

    Next Steps for RKE Kubernetes Cluster Nodes​

    If you are going to install an RKE cluster on the new nodes, take note of the IPv4 Public IP and Private IP of each node. This information can be found on the Description tab for each node after it is created. The public and private IP will be used to populate the address and internal_address of each node in the RKE cluster configuration file, rancher-cluster.yml.

    RKE will also need access to the private key to connect to each node. Therefore, you might want to take note of the path to your private keys to connect to the nodes, which can also be included in the rancher-cluster.yml under the ssh_key_path directive for each node.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html index ed5a892068b..9507603f36c 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/high-availability-installs.html @@ -5,13 +5,13 @@ About High-availability Installations | Rancher Manager - +
    Version: v2.5

    About High-availability Installations

    We recommend using Helm, a Kubernetes package manager, to install Rancher on a dedicated Kubernetes cluster. This is called a high-availability Kubernetes installation because increased availability is achieved by running Rancher on multiple nodes.

    In a standard installation, Kubernetes is first installed on three nodes that are hosted in an infrastructure provider such as Amazon's EC2 or Google Compute Engine.

    Then Helm is used to install Rancher on top of the Kubernetes cluster. Helm uses Rancher's Helm chart to install a replica of Rancher on each of the three nodes in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster, in order to increase Rancher's availability.

    The Rancher server data is stored on etcd. This etcd database also runs on all three nodes, and requires an odd number of nodes so that it can always elect a leader with a majority of the etcd cluster. If the etcd database cannot elect a leader, etcd can fail, requiring the cluster to be restored from backup.

    For information on how Rancher works, regardless of the installation method, refer to the architecture section.

    • DNS for Rancher should resolve to a layer 4 load balancer
    • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
    • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
    • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
    Kubernetes Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers

    High-availability Kubernetes Installation of Rancher

    Kubernetes Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html index bd910e5c317..ab409e076e0 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/k3s-for-rancher.html @@ -5,14 +5,14 @@ Setting up a High-availability K3s Kubernetes Cluster for Rancher | Rancher Manager - +
    Version: v2.5

    Setting up a High-availability K3s Kubernetes Cluster for Rancher

    This section describes how to install a Kubernetes cluster according to the best practices for the Rancher server environment.

    For systems without direct internet access, refer to the air gap installation instructions.

    Single-node Installation Tip: In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node K3s cluster, run the Rancher server installation command on just one node instead of two nodes.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Prerequisites

    These instructions assume you have set up two nodes, a load balancer, a DNS record, and an external MySQL database as described in this section.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

    Installing Kubernetes

    1. Install Kubernetes and Set up the K3s Server​

    When running the command to start the K3s Kubernetes API server, you will pass in an option to use the external datastore that you set up earlier.

    1. Connect to one of the Linux nodes that you have prepared to run the Rancher server.

    2. On the Linux node, run this command to start the K3s server and connect it to the external datastore:

      curl -sfL https://get.k3s.io | sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"

      To specify the K3s version, use the INSTALL_K3S_VERSION environment variable:

      curl -sfL https://get.k3s.io |  INSTALL_K3S_VERSION=vX.Y.Z sh -s - server \
        --datastore-endpoint="mysql://username:password@tcp(hostname:3306)/database-name"

      Note: The datastore endpoint can also be passed in using the environment variable $K3S_DATASTORE_ENDPOINT.

    3. Repeat the same command on your second K3s server node.

    2. Confirm that K3s is Running​

    To confirm that K3s has been set up successfully, run the following command on either of the K3s server nodes:

    sudo k3s kubectl get nodes

    Then you should see two nodes with the master role:

    ubuntu@ip-172-31-60-194:~$ sudo k3s kubectl get nodes
    NAME               STATUS   ROLES    AGE    VERSION
    ip-172-31-60-194   Ready    master   44m    v1.17.2+k3s1
    ip-172-31-63-88    Ready    master   6m8s   v1.17.2+k3s1

    Then test the health of the cluster pods:

    sudo k3s kubectl get pods --all-namespaces

    Result: You have successfully set up a K3s Kubernetes cluster.

    3. Save and Start Using the kubeconfig File​

    When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    4. Check the Health of Your Cluster Pods​

    Now that you have set up the kubeconfig file, you can use kubectl to access the cluster from your local machine.

    Check that all the required pods and containers are healthy are ready to continue:

    ubuntu@ip-172-31-60-194:~$ sudo kubectl get pods --all-namespaces
    NAMESPACE       NAME                                      READY   STATUS    RESTARTS   AGE
    kube-system     metrics-server-6d684c7b5-bw59k            1/1     Running   0          8d
    kube-system     local-path-provisioner-58fb86bdfd-fmkvd   1/1     Running   0          8d
    kube-system     coredns-d798c9dd-ljjnf                    1/1     Running   0          8d

    Result: You have confirmed that you can access the cluster with kubectl and the K3s cluster is running successfully. Now the Rancher management server can be installed on the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html index 049ac2edbb5..15e3c87448b 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke1-for-rancher.html @@ -5,7 +5,7 @@ Setting up a High-availability RKE Kubernetes Cluster | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Setting up a High-availability RKE Kubernetes Cluster

    This section describes how to install a Kubernetes cluster. This cluster should be dedicated to run only the Rancher server.

    As of Rancher v2.5, Rancher can run on any Kubernetes cluster, included hosted Kubernetes solutions such as Amazon EKS. The below instructions represent only one possible way to install Kubernetes.

    For systems without direct internet access, refer to Air Gap: Kubernetes install.

    Single-node Installation Tip: In a single-node Kubernetes cluster, the Rancher server does not have high availability, which is important for running Rancher in production. However, installing Rancher on a single-node cluster can be useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path.

    To set up a single-node RKE cluster, configure only one node in the cluster.yml . The single node should have all three roles: etcd, controlplane, and worker.

    In both single-node setups, Rancher can be installed with Helm on the Kubernetes cluster in the same way that it would be installed on any other cluster.

    Installing Kubernetes

    Required CLI Tools​

    Install kubectl, a Kubernetes command-line tool.

    Also install RKE, the Rancher Kubernetes Engine, a Kubernetes distribution and command-line tool.

    1. Create the cluster configuration file​

    In this section, you will create a Kubernetes cluster configuration file called rancher-cluster.yml. In a later step, when you set up the cluster with an RKE command, it will use this file to install Kubernetes on your nodes.

    Using the sample below as a guide, create the rancher-cluster.yml file. Replace the IP addresses in the nodes list with the IP address or DNS names of the 3 nodes you created.

    If your node has public and internal addresses, it is recommended to set the internal_address: so Kubernetes will use it for intra-cluster communication. Some services like AWS EC2 require setting the internal_address: if you want to use self-referencing security groups or firewalls.

    RKE will need to connect to each node over SSH, and it will look for a private key in the default location of ~/.ssh/id_rsa. If your private key for a certain node is in a different location than the default, you will also need to configure the ssh_key_path option for that node.

    nodes:
      - address: 165.227.114.63
        internal_address: 172.16.22.12
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.116.167
        internal_address: 172.16.32.37
        user: ubuntu
        role: [controlplane, worker, etcd]
      - address: 165.227.127.226
        internal_address: 172.16.42.73
        user: ubuntu
        role: [controlplane, worker, etcd]

    services:
      etcd:
        snapshot: true
        creation: 6h
        retention: 24h

    # Required for external TLS termination with
    # ingress-nginx v0.22+
    ingress:
      provider: nginx
      options:
        use-forwarded-headers: "true"
    Common RKE Nodes Options
    OptionRequiredDescription
    addressyesThe public DNS or IP address
    useryesA user that can run docker commands
    roleyesList of Kubernetes roles assigned to the node
    internal_addressnoThe private DNS or IP address for internal cluster traffic
    ssh_key_pathnoPath to SSH private key used to authenticate to the node (defaults to ~/.ssh/id_rsa)

    Advanced Configurations: RKE has many configuration options for customizing the install to suit your specific environment.

    Please see the RKE Documentation for the full list of options and capabilities.

    For tuning your etcd cluster for larger Rancher installations, see the etcd settings guide.

    2. Run RKE​

    rke up --config ./rancher-cluster.yml

    When finished, it should end with the line: Finished building Kubernetes cluster successfully.

    3. Test Your Cluster​

    This section describes how to set up your workspace so that you can interact with this cluster using the kubectl command-line tool.

    Assuming you have installed kubectl, you need to place the kubeconfig file in a location where kubectl can reach it. The kubeconfig file contains the credentials necessary to access your cluster with kubectl.

    When you ran rke up, RKE should have created a kubeconfig file named kube_config_cluster.yml. This file has the credentials for kubectl and helm.

    Note: If you have used a different file name from rancher-cluster.yml, then the kube config file will be named kube_config_<FILE_NAME>.yml.

    Move this file to $HOME/.kube/config, or if you are working with multiple Kubernetes clusters, set the KUBECONFIG environmental variable to the path of kube_config_cluster.yml:

    export KUBECONFIG=$(pwd)/kube_config_cluster.yml

    Test your connectivity with kubectl and see if all your nodes are in Ready state:

    kubectl get nodes

    NAME                          STATUS    ROLES                      AGE       VERSION
    165.227.114.63                Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.116.167               Ready     controlplane,etcd,worker   11m       v1.13.5
    165.227.127.226               Ready     controlplane,etcd,worker   11m       v1.13.5

    4. Check the Health of Your Cluster Pods​

    Check that all the required pods and containers are healthy are ready to continue.

    • Pods are in Running or Completed state.
    • READY column shows all the containers are running (i.e. 3/3) for pods with STATUS Running
    • Pods with STATUS Completed are run-once Jobs. For these pods READY should be 0/1.
    kubectl get pods --all-namespaces

    NAMESPACE       NAME                                      READY     STATUS      RESTARTS   AGE
    ingress-nginx   nginx-ingress-controller-tnsn4            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-tw2ht            1/1       Running     0          30s
    ingress-nginx   nginx-ingress-controller-v874b            1/1       Running     0          30s
    kube-system     canal-jp4hz                               3/3       Running     0          30s
    kube-system     canal-z2hg8                               3/3       Running     0          30s
    kube-system     canal-z6kpw                               3/3       Running     0          30s
    kube-system     kube-dns-7588d5b5f5-sf4vh                 3/3       Running     0          30s
    kube-system     kube-dns-autoscaler-5db9bbb766-jz2k6      1/1       Running     0          30s
    kube-system     metrics-server-97bc649d5-4rl2q            1/1       Running     0          30s
    kube-system     rke-ingress-controller-deploy-job-bhzgm   0/1       Completed   0          30s
    kube-system     rke-kubedns-addon-deploy-job-gl7t4        0/1       Completed   0          30s
    kube-system     rke-metrics-addon-deploy-job-7ljkc        0/1       Completed   0          30s
    kube-system     rke-network-plugin-deploy-job-6pbgj       0/1       Completed   0          30s

    This confirms that you have successfully installed a Kubernetes cluster that the Rancher server will run on.

    5. Save Your Files​

    Important The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster.

    Save a copy of the following files in a secure location:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster.
    • rancher-cluster.rkestate: The Kubernetes Cluster State file, this file contains credentials for full access to the cluster.

      The Kubernetes Cluster State file is only created when using RKE v0.2.0 or higher.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    Issues or errors?​

    See the Troubleshooting page.

    Next: Install Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html index d2cb3dc1acd..5d902d2f2dd 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.html @@ -5,13 +5,13 @@ Setting up a High-availability RKE2 Kubernetes Cluster for Rancher | Rancher Manager - +
    Version: v2.5

    Setting up a High-availability RKE2 Kubernetes Cluster for Rancher

    Tested on v2.5.6

    This section describes how to install a Kubernetes cluster according to the best practices for the Rancher server environment.

    Prerequisites

    These instructions assume you have set up three nodes, a load balancer, and a DNS record, as described in this section.

    Note that in order for RKE2 to work correctly with the load balancer, you need to set up two listeners: one for the supervisor on port 9345, and one for the Kubernetes API on port 6443.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the RKE2 version, use the INSTALL_RKE2_VERSION environment variable when running the RKE2 installation script.

    Installing Kubernetes

    1. Install Kubernetes and Set up the RKE2 Server​

    RKE2 server runs with embedded etcd so you will not need to set up an external datastore to run in HA mode.

    On the first node, you should set up the configuration file with your own pre-shared secret as the token. The token argument can be set on startup.

    If you do not specify a pre-shared secret, RKE2 will generate one and place it at /var/lib/rancher/rke2/server/node-token.

    To avoid certificate errors with the fixed registration address, you should launch the server with the tls-san parameter set. This option adds an additional hostname or IP as a Subject Alternative Name in the server's TLS cert, and it can be specified as a list if you would like to access via both the IP and the hostname.

    First, you must create the directory where the RKE2 config file is going to be placed:

    mkdir -p /etc/rancher/rke2/

    Next, create the RKE2 config file at /etc/rancher/rke2/config.yaml using the following example:

    token: my-shared-secret
    tls-san:
      - my-kubernetes-domain.com
      - another-kubernetes-domain.com

    After that, you need to run the install command and enable and start rke2:

    curl -sfL https://get.rke2.io | INSTALL_RKE2_CHANNEL=v1.20 sh -
    systemctl enable rke2-server.service
    systemctl start rke2-server.service

    1. To join the rest of the nodes, you need to configure each additional node with the same shared token or the one generated automatically. Here is an example of the configuration file:

          token: my-shared-secret
          server: https://<DNS-DOMAIN>:9345
          tls-san:
            - my-kubernetes-domain.com
            - another-kubernetes-domain.com

      After that, you need to run the installer and enable, then start, rke2:

          curl -sfL https://get.rke2.io | sh -
          systemctl enable rke2-server.service
          systemctl start rke2-server.service
    1. Repeat the same command on your third RKE2 server node.

    2. Confirm that RKE2 is Running​

    Once you've launched the rke2 server process on all server nodes, ensure that the cluster has come up properly with

    /var/lib/rancher/rke2/bin/kubectl \
            --kubeconfig /etc/rancher/rke2/rke2.yaml get nodes
    You should see your server nodes in the Ready state.

    Then test the health of the cluster pods:

    /var/lib/rancher/rke2/bin/kubectl \
            --kubeconfig /etc/rancher/rke2/rke2.yaml get pods --all-namespaces

    Result: You have successfully set up a RKE2 Kubernetes cluster.

    3. Save and Start Using the kubeconfig File​

    When you installed RKE2 on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/rke2/rke2.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

    To use this kubeconfig file,

    1. Install kubectl, a Kubernetes command-line tool.
    2. Copy the file at /etc/rancher/rke2/rke2.yaml and save it to the directory ~/.kube/config on your local machine.
    3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example rke2.yaml:
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: [CERTIFICATE-DATA]
        server: [LOAD-BALANCER-DNS]:6443 # Edit this line
      name: default
    contexts:
    - context:
        cluster: default
        user: default
      name: default
    current-context: default
    kind: Config
    preferences: {}
    users:
    - name: default
      user:
        password: [PASSWORD]
        username: admin

    Result: You can now use kubectl to manage your RKE2 cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

    kubectl --kubeconfig ~/.kube/config/rke2.yaml get pods --all-namespaces

    For more information about the kubeconfig file, refer to the RKE2 documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

    4. Check the Health of Your Cluster Pods​

    Now that you have set up the kubeconfig file, you can use kubectl to access the cluster from your local machine.

    Check that all the required pods and containers are healthy are ready to continue:

     /var/lib/rancher/rke2/bin/kubectl         --kubeconfig /etc/rancher/rke2/rke2.yaml get pods -A
    NAMESPACE     NAME                                                 READY   STATUS      RESTARTS   AGE
    kube-system   etcd-ip-172-31-18-145                                1/1     Running     0          4m37s
    kube-system   etcd-ip-172-31-25-73                                 1/1     Running     0          20m
    kube-system   etcd-ip-172-31-31-210                                1/1     Running     0          9m12s
    kube-system   helm-install-rke2-canal-th9k9                        0/1     Completed   0          21m
    kube-system   helm-install-rke2-coredns-6njr6                      0/1     Completed   0          21m
    kube-system   helm-install-rke2-ingress-nginx-vztsd                0/1     Completed   0          21m
    kube-system   helm-install-rke2-kube-proxy-6std5                   0/1     Completed   0          21m
    kube-system   helm-install-rke2-metrics-server-9sl7m               0/1     Completed   0          21m
    kube-system   kube-apiserver-ip-172-31-18-145                      1/1     Running     0          4m22s
    kube-system   kube-apiserver-ip-172-31-25-73                       1/1     Running     0          20m
    kube-system   kube-apiserver-ip-172-31-31-210                      1/1     Running     0          9m8s
    kube-system   kube-controller-manager-ip-172-31-18-145             1/1     Running     0          4m8s
    kube-system   kube-controller-manager-ip-172-31-25-73              1/1     Running     0          21m
    kube-system   kube-controller-manager-ip-172-31-31-210             1/1     Running     0          8m55s
    kube-system   kube-proxy-57twm                                     1/1     Running     0          10m
    kube-system   kube-proxy-f7pc6                                     1/1     Running     0          5m24s
    kube-system   kube-proxy-rj4t5                                     1/1     Running     0          21m
    kube-system   kube-scheduler-ip-172-31-18-145                      1/1     Running     0          4m15s
    kube-system   kube-scheduler-ip-172-31-25-73                       1/1     Running     0          21m
    kube-system   kube-scheduler-ip-172-31-31-210                      1/1     Running     0          8m48s
    kube-system   rke2-canal-4x972                                     2/2     Running     0          10m
    kube-system   rke2-canal-flh8m                                     2/2     Running     0          5m24s
    kube-system   rke2-canal-zfhkr                                     2/2     Running     0          21m
    kube-system   rke2-coredns-rke2-coredns-6cd96645d6-cmstq           1/1     Running     0          21m
    kube-system   rke2-ingress-nginx-controller-54946dd48f-6mp76       1/1     Running     0          20m
    kube-system   rke2-ingress-nginx-default-backend-5795954f8-p92xx   1/1     Running     0          20m
    kube-system   rke2-metrics-server-5f9b5757dc-k5sgh                 1/1     Running     0          20m

    Result: You have confirmed that you can access the cluster with kubectl and the RKE2 cluster is running successfully. Now the Rancher management server can be installed on the cluster.

    5. Configure nginx to be a daemonset​

    Currently, RKE2 deploys nginx-ingress as a deployment, and that can impact the Rancher deployment so that you cannot use all servers to proxy requests to the Rancher pods.

    To rectify that, place the following file in /var/lib/rancher/rke2/server/manifests on any of the server nodes:

    apiVersion: helm.cattle.io/v1
    kind: HelmChartConfig
    metadata:
      name: rke2-ingress-nginx
      namespace: kube-system
    spec:
      valuesContent: |-
        controller:
          kind: DaemonSet
          daemonset:
            useHostPort: true
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html index 375187d474d..cf961aa91a7 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/recommended-cluster-architecture.html @@ -5,13 +5,13 @@ Recommended Cluster Architecture | Rancher Manager - +
    Version: v2.5

    Recommended Cluster Architecture

    There are three roles that can be assigned to nodes: etcd, controlplane and worker.

    Separating Worker Nodes from Nodes with Other Roles​

    When designing your cluster(s), you have two options:

    • Use dedicated nodes for each role. This ensures resource availability for the components needed for the specified role. It also strictly isolates network traffic between each of the roles according to the port requirements.
    • Assign the etcd and controlplane roles to the same nodes. These nodes must meet the hardware requirements for both roles.

    In either case, the worker role should not be used or added to nodes with the etcd or controlplane role.

    Therefore, each node should have one of the following role configurations:

    • etcd
    • controlplane
    • Both etcd and controlplane
    • worker

    The cluster should have:

    • At least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • At least two nodes with the role controlplane for master component high availability.
    • At least two nodes with the role worker for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    Number of Controlplane Nodes​

    Adding more than one node with the controlplane role makes every master component highly available.

    Number of etcd Nodes​

    The number of nodes that you can lose at once while maintaining cluster availability is determined by the number of nodes assigned the etcd role. For a cluster with n members, the minimum is (n/2)+1. Therefore, we recommend creating an etcd node in 3 different availability zones within a region to survive the loss of one availability zone. If you use only two zones, you can only survive the loss of the zone where you don't lose the majority of nodes.

    Nodes with etcd roleMajorityFailure Tolerance
    110
    220
    321
    431
    532
    642
    743
    853
    954

    References:

    Number of Worker Nodes​

    Adding more than one node with the worker role will make sure your workloads can be rescheduled if a node fails.

    Why Production Requirements are Different for the Rancher Cluster and the Clusters Running Your Applications​

    You may have noticed that our Kubernetes Install instructions do not meet our definition of a production-ready cluster, as there are no dedicated nodes for the worker role. However, for your Rancher installation, this three node cluster is valid, because:

    • It allows one etcd node failure.
    • It maintains multiple instances of the master components by having multiple controlplane nodes.
    • No other workloads than Rancher itself should be created on this cluster.

    References​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html index 1698d149470..b5b6e67e6d5 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/checklist-for-production-ready-clusters/roles-for-nodes-in-kubernetes.html @@ -5,13 +5,13 @@ Roles for Nodes in Kubernetes | Rancher Manager - +
    Version: v2.5

    Roles for Nodes in Kubernetes

    This section describes the roles for etcd nodes, controlplane nodes, and worker nodes in Kubernetes, and how the roles work together in a cluster.

    This diagram is applicable to Kubernetes clusters launched with Rancher using RKE..

    Cluster diagram

    Lines show the traffic flow between components. Colors are used purely for visual aid

    etcd

    Nodes with the etcd role run etcd, which is a consistent and highly available key value store used as Kubernetes’ backing store for all cluster data. etcd replicates the data to each node.

    Note: Nodes with the etcd role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    controlplane

    Nodes with the controlplane role run the Kubernetes master components (excluding etcd, as it's a separate role). See Kubernetes: Master Components for a detailed list of components.

    Note: Nodes with the controlplane role are shown as Unschedulable in the UI, meaning no pods will be scheduled to these nodes by default.

    kube-apiserver​

    The Kubernetes API server (kube-apiserver) scales horizontally. Each node with the role controlplane will be added to the NGINX proxy on the nodes with components that need to access the Kubernetes API server. This means that if a node becomes unreachable, the local NGINX proxy on the node will forward the request to another Kubernetes API server in the list.

    kube-controller-manager​

    The Kubernetes controller manager uses leader election using an endpoint in Kubernetes. One instance of the kube-controller-manager will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    kube-scheduler​

    The Kubernetes scheduler uses leader election using an endpoint in Kubernetes. One instance of the kube-scheduler will create an entry in the Kubernetes endpoints and updates that entry in a configured interval. Other instances will see an active leader and wait for that entry to expire (for example, when a node is unresponsive).

    worker

    Nodes with the worker role run the Kubernetes node components. See Kubernetes: Node Components for a detailed list of components.

    References

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html index 4e979756818..18415980212 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/about-rancher-agents.html @@ -5,13 +5,13 @@ Rancher Agents | Rancher Manager - +
    Version: v2.5

    Rancher Agents

    There are two different agent resources deployed on Rancher managed clusters:

    For a conceptual overview of how the Rancher server provisions clusters and communicates with them, refer to the architecture

    cattle-cluster-agent​

    The cattle-cluster-agent is used to connect to the Kubernetes API of Rancher Launched Kubernetes clusters. The cattle-cluster-agent is deployed using a Deployment resource.

    cattle-node-agent​

    The cattle-node-agent is used to interact with nodes in a Rancher Launched Kubernetes cluster when performing cluster operations. Examples of cluster operations are upgrading Kubernetes version and creating/restoring etcd snapshots. The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node. The cattle-node-agent is used as fallback option to connect to the Kubernetes API of Rancher Launched Kubernetes clusters when cattle-cluster-agent is unavailable.

    Scheduling rules​

    Applies to v2.5.4 and higher

    Starting with Rancher v2.5.4, the tolerations for the cattle-cluster-agent changed from operator:Exists (allowing all taints) to a fixed set of tolerations (listed below, if no controlplane nodes are visible in the cluster) or dynamically added tolerations based on taints applied to the controlplane nodes. This change was made to allow Taint based Evictions to work properly for cattle-cluster-agent. The default tolerations are described below. If controlplane nodes are present the cluster, the tolerations will be replaced with tolerations matching the taints on the controlplane nodes.

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneNote: These are the default tolerations, and will be replaced by tolerations matching taints applied to controlplane nodes.

    effect:NoSchedule
    key:node-role.kubernetes.io/controlplane
    value:true

    effect:NoSchedule
    key:node-role.kubernetes.io/control-plane
    operator:Exists

    effect:NoSchedule
    key:node-role.kubernetes.io/master
    operator:Exists
    cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

    The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. When there are no controlplane nodes visible in the cluster (this is usually the case when using Clusters from Hosted Kubernetes Providers), you can add the label cattle.io/cluster-agent=true on a node to prefer scheduling the cattle-cluster-agent pod to that node.

    See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

    The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

    WeightExpression
    100node-role.kubernetes.io/controlplane:In:"true"
    100node-role.kubernetes.io/control-plane:In:"true"
    100node-role.kubernetes.io/master:In:"true"
    1cattle.io/cluster-agent:In:"true"

    Applies to v2.3.0 up to v2.5.3

    ComponentnodeAffinity nodeSelectorTermsnodeSelectorTolerations
    cattle-cluster-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists
    cattle-node-agentbeta.kubernetes.io/os:NotIn:windowsnoneoperator:Exists

    The cattle-cluster-agent Deployment has preferred scheduling rules using preferredDuringSchedulingIgnoredDuringExecution, favoring to be scheduled on nodes with the controlplane node. See Kubernetes: Assigning Pods to Nodes to find more information about scheduling rules.

    The preferredDuringSchedulingIgnoredDuringExecution configuration is shown in the table below:

    WeightExpression
    100node-role.kubernetes.io/controlplane:In:"true"
    1node-role.kubernetes.io/etcd:In:"true"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html index bf3238450be..682a5da21f6 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/amazon.html @@ -5,13 +5,13 @@ Setting up the Amazon Cloud Provider | Rancher Manager - +
    Version: v2.5

    Setting up the Amazon Cloud Provider

    When using the Amazon cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an AWS Elastic Load Balancer (ELB) when choosing Layer-4 Load Balancer in Port Mapping or when launching a Service with type: LoadBalancer.
    • Persistent Volumes: Allows you to use AWS Elastic Block Stores (EBS) for persistent volumes.

    See cloud-provider-aws README for all information regarding the Amazon cloud provider.

    To set up the Amazon cloud provider,

    1. Create an IAM role and attach to the instances
    2. Configure the ClusterID

    1. Create an IAM Role and attach to the instances​

    All nodes added to the cluster must be able to interact with EC2 so that they can create and remove resources. You can enable this interaction by using an IAM role attached to the instance. See Amazon documentation: Creating an IAM Role how to create an IAM role. There are two example policies:

    • The first policy is for the nodes with the controlplane role. These nodes have to be able to create/remove EC2 resources. The following IAM policy is an example, please remove any unneeded permissions for your use case.
    • The second policy is for the nodes with the etcd or worker role. These nodes only have to be able to retrieve information from EC2.

    While creating an Amazon EC2 cluster, you must fill in the IAM Instance Profile Name (not ARN) of the created IAM role when creating the Node Template.

    While creating a Custom cluster, you must manually attach the IAM role to the instance(s).

    IAM Policy for nodes with the controlplane role:

    {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "autoscaling:DescribeAutoScalingGroups",
          "autoscaling:DescribeLaunchConfigurations",
          "autoscaling:DescribeTags",
          "ec2:DescribeInstances",
          "ec2:DescribeRegions",
          "ec2:DescribeRouteTables",
          "ec2:DescribeSecurityGroups",
          "ec2:DescribeSubnets",
          "ec2:DescribeVolumes",
          "ec2:CreateSecurityGroup",
          "ec2:CreateTags",
          "ec2:CreateVolume",
          "ec2:ModifyInstanceAttribute",
          "ec2:ModifyVolume",
          "ec2:AttachVolume",
          "ec2:AuthorizeSecurityGroupIngress",
          "ec2:CreateRoute",
          "ec2:DeleteRoute",
          "ec2:DeleteSecurityGroup",
          "ec2:DeleteVolume",
          "ec2:DetachVolume",
          "ec2:RevokeSecurityGroupIngress",
          "ec2:DescribeVpcs",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:AttachLoadBalancerToSubnets",
          "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancer",
          "elasticloadbalancing:CreateLoadBalancerPolicy",
          "elasticloadbalancing:CreateLoadBalancerListeners",
          "elasticloadbalancing:ConfigureHealthCheck",
          "elasticloadbalancing:DeleteLoadBalancer",
          "elasticloadbalancing:DeleteLoadBalancerListeners",
          "elasticloadbalancing:DescribeLoadBalancers",
          "elasticloadbalancing:DescribeLoadBalancerAttributes",
          "elasticloadbalancing:DetachLoadBalancerFromSubnets",
          "elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
          "elasticloadbalancing:ModifyLoadBalancerAttributes",
          "elasticloadbalancing:RegisterInstancesWithLoadBalancer",
          "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer",
          "elasticloadbalancing:AddTags",
          "elasticloadbalancing:CreateListener",
          "elasticloadbalancing:CreateTargetGroup",
          "elasticloadbalancing:DeleteListener",
          "elasticloadbalancing:DeleteTargetGroup",
          "elasticloadbalancing:DescribeListeners",
          "elasticloadbalancing:DescribeLoadBalancerPolicies",
          "elasticloadbalancing:DescribeTargetGroups",
          "elasticloadbalancing:DescribeTargetHealth",
          "elasticloadbalancing:ModifyListener",
          "elasticloadbalancing:ModifyTargetGroup",
          "elasticloadbalancing:RegisterTargets",
          "elasticloadbalancing:SetLoadBalancerPoliciesOfListener",
          "iam:CreateServiceLinkedRole",
          "kms:DescribeKey"
        ],
        "Resource": [
          "*"
        ]
      }
    ]
    }

    IAM policy for nodes with the etcd or worker role:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "ec2:DescribeRegions",
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:GetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:BatchGetImage"
            ],
            "Resource": "*"
        }
    ]
    }

    2. Configure the ClusterID​

    The following resources need to tagged with a ClusterID:

    • Nodes: All hosts added in Rancher.
    • Subnet: The subnet used for your cluster.
    • Security Group: The security group used for your cluster.

    Note: Do not tag multiple security groups. Tagging multiple groups generates an error when creating an Elastic Load Balancer (ELB).

    When you create an Amazon EC2 Cluster, the ClusterID is automatically configured for the created nodes. Other resources still need to be tagged manually.

    Use the following tag:

    Key = kubernetes.io/cluster/CLUSTERID Value = owned

    CLUSTERID can be any string you like, as long as it is equal across all tags set.

    Setting the value of the tag to owned tells the cluster that all resources with this tag are owned and managed by this cluster. If you share resources between clusters, you can change the tag to:

    Key = kubernetes.io/cluster/CLUSTERID Value = shared.

    Using Amazon Elastic Container Registry (ECR)​

    The kubelet component has the ability to automatically obtain ECR credentials, when the IAM profile mentioned in Create an IAM Role and attach to the instances is attached to the instance(s). When using a Kubernetes version older than v1.15.0, the Amazon cloud provider needs be configured in the cluster. Starting with Kubernetes version v1.15.0, the kubelet can obtain ECR credentials without having the Amazon cloud provider configured in the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html index 83cc94119d1..918896a77f3 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/azure.html @@ -5,13 +5,13 @@ Setting up the Azure Cloud Provider | Rancher Manager - +
    Version: v2.5

    Setting up the Azure Cloud Provider

    When using the Azure cloud provider, you can leverage the following capabilities:

    • Load Balancers: Launches an Azure Load Balancer within a specific Network Security Group.

    • Persistent Volumes: Supports using Azure Blob disks and Azure Managed Disks with standard and premium storage accounts.

    • Network Storage: Support Azure Files via CIFS mounts.

    The following account types are not supported for Azure Subscriptions:

    • Single tenant accounts (i.e. accounts with no subscriptions).
    • Multi-subscription accounts.

    To set up the Azure cloud provider following credentials need to be configured:

    1. Set up the Azure Tenant ID
    2. Set up the Azure Client ID and Azure Client Secret
    3. Configure App Registration Permissions
    4. Set up Azure Network Security Group Name

    1. Set up the Azure Tenant ID​

    Visit Azure portal, login and go to Azure Active Directory and select Properties. Your Directory ID is your Tenant ID (tenantID).

    If you want to use the Azure CLI, you can run the command az account show to get the information.

    2. Set up the Azure Client ID and Azure Client Secret​

    Visit Azure portal, login and follow the steps below to create an App Registration and the corresponding Azure Client ID (aadClientId) and Azure Client Secret (aadClientSecret).

    1. Select Azure Active Directory.
    2. Select App registrations.
    3. Select New application registration.
    4. Choose a Name, select Web app / API as Application Type and a Sign-on URL which can be anything in this case.
    5. Select Create.

    In the App registrations view, you should see your created App registration. The value shown in the column APPLICATION ID is what you need to use as Azure Client ID.

    The next step is to generate the Azure Client Secret:

    1. Open your created App registration.
    2. In the Settings view, open Keys.
    3. Enter a Key description, select an expiration time and select Save.
    4. The generated value shown in the column Value is what you need to use as Azure Client Secret. This value will only be shown once.

    3. Configure App Registration Permissions​

    The last thing you will need to do, is assign the appropriate permissions to your App registration.

    1. Go to More services, search for Subscriptions and open it.
    2. Open Access control (IAM).
    3. Select Add.
    4. For Role, select Contributor.
    5. For Select, select your created App registration name.
    6. Select Save.

    4. Set up Azure Network Security Group Name​

    A custom Azure Network Security Group (securityGroupName) is needed to allow Azure Load Balancers to work.

    If you provision hosts using Rancher Machine Azure driver, you will need to edit them manually to assign them to this Network Security Group.

    You should already assign custom hosts to this Network Security Group during provisioning.

    Only hosts expected to be load balancer back ends need to be in this group.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html index b4afd9c2081..8d8eb713942 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/other-cloud-providers/google-compute-engine.html @@ -5,13 +5,13 @@ Setting up the Google Compute Engine Cloud Provider | Rancher Manager - +
    Version: v2.5

    Setting up the Google Compute Engine Cloud Provider

    In this section, you'll learn how to enable the Google Compute Engine (GCE) cloud provider for custom clusters in Rancher. A custom cluster is one in which Rancher installs Kubernetes on existing nodes.

    The official Kubernetes documentation for the GCE cloud provider is here.

    Prerequisites: The service account of Identity and API access on GCE needs the Computer Admin permission.

    If you are using Calico,

    1. Go to the cluster view in the Rancher UI, and click ⋮ > Edit.

    2. Click Edit as YAML, and enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        network:
          options:
            calico_cloud_provider: "gce"
          plugin: "calico"

    If you are using Canal or Flannel,

    1. Go to the cluster view in the Rancher UI, and click ⋮ > Edit.

    2. Click Edit as YAML, and enter the following configuration:

      rancher_kubernetes_engine_config:
        cloud_provider:
          name: gce
          customCloudProvider: |-
            [Global]
            project-id=<your project ID, optional>
            network-name=<your network, optional if using default network>
            subnetwork-name=<your subnetwork of the above network, optional if using default network>
            node-instance-prefix=<your instance group name/your instance name specific prefix, required>
            node-tags=<your network tags, must patch one or some tags, required>
        services:
          kube_controller:
            extra_args:
              configure-cloud-routes: true # we need to allow the cloud provider configure the routes for the hosts
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html index 9fc4e49496f..f2824bb609c 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-in-tree-vsphere.html @@ -5,13 +5,13 @@ How to Configure In-tree vSphere Cloud Provider | Rancher Manager - +
    Version: v2.5

    How to Configure In-tree vSphere Cloud Provider

    To set up the in-tree vSphere cloud provider, follow these steps while creating the vSphere cluster in Rancher:

    1. Set Cloud Provider option to Custom or Custom (In-Tree).

    2. Click on Edit as YAML

    3. Insert the following structure to the pre-populated cluster YAML. This structure must be placed under rancher_kubernetes_engine_config. Note that the name must be set to vsphere.

      rancher_kubernetes_engine_config:
        cloud_provider:
            name: vsphere
            vsphereCloudProvider:
                [Insert provider configuration]

    Rancher uses RKE (the Rancher Kubernetes Engine) to provision Kubernetes clusters. Refer to the vSphere configuration reference in the RKE documentation for details about the properties of the vsphereCloudProvider directive.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html index d8f329acd89..7ba1a388a7f 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/configure-out-of-tree-vsphere.html @@ -5,13 +5,13 @@ How to Configure Out-of-tree vSphere Cloud Provider | Rancher Manager - +
    Version: v2.5

    How to Configure Out-of-tree vSphere Cloud Provider

    Available as of v2.5+

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    This page covers how to install the Cloud Provider Interface (CPI) and Cloud Storage Interface (CSI) plugins after bringing up a cluster.

    Prerequisites

    The vSphere versions supported:

    • 6.7u3
    • 7.0u1 or higher.

    The Kubernetes version must be 1.19 or higher.

    Using the vSphere out-of-tree cloud provider requires Linux nodes and is not supported on Windows.

    Installation

    The Cloud Provider Interface (CPI) should be installed first before installing the Cloud Storage Interface (CSI).

    1. Create a vSphere cluster​

    1. On the Clusters page, click on Add Cluster and select the vSphere option or Existing Nodes option.
    2. Under Cluster Options in the Cloud Provider section, select External (Out-of-tree). This sets the cloud provider option on the Kubernetes cluster to external which sets your Kubernetes cluster up to be configured with an out-of-tree cloud provider.
    3. Finish creating your cluster.

    2. Install the CPI plugin​

    1. From the Cluster Explorer view, go to the top left dropdown menu and click Apps & Marketplace.

    2. Select the vSphere CPI chart. Fill out the required vCenter details.

    3. vSphere CPI initializes all nodes with ProviderID which is needed by the vSphere CSI driver. Check if all nodes are initialized with the ProviderID before installing CSI driver with the following command:

      kubectl describe nodes | grep "ProviderID"

    3. Installing the CSI plugin​

    1. From the Cluster Explorer view, go to the top left dropdown menu and click Apps & Marketplace.
    2. Select the vSphere CSI chart. Fill out the required vCenter details.
    3. Set Enable CSI Migration to false.
    4. This chart creates a StorageClass with the csi.vsphere.vmware.com as the provisioner. Fill out the details for the StorageClass and launch the chart.

    Using the CSI driver for provisioning volumes

    The CSI chart by default creates a storageClass.

    If that option was not selected while launching the chart, create a storageClass with the csi.vsphere.vmware.com as the provisioner.

    All volumes provisioned using this StorageClass will get provisioned by the CSI driver.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html index 58ff5106485..ba9df95fb0c 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/set-up-cloud-providers/vsphere/migrate-from-in-tree-to-out-of-tree.html @@ -5,13 +5,13 @@ Migrating vSphere In-tree Volumes to CSI | Rancher Manager - +
    Version: v2.5

    Migrating vSphere In-tree Volumes to CSI

    Available as of v2.5+

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    This page covers how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration.

    It follows the steps provided in the official vSphere migration documentation and provides the steps to be performed in Rancher.

    Cloud-config Format Limitation​

    Existing volumes that were provisioned using the following cloud-config format will NOT get migrated due to an existing bug in vsphere CSI.

    If the cloud-config has this format for datastore and resource pool path, vsphere CSI driver cannot recognize it:

    default-datastore: </datacenter>/datastore/<default-datastore-name>
    resourcepool-path: "</datacenter>/host/<cluster-name>/Resources/<resource-pool-name>"

    Volumes provisioned with the in-tree provider using the following format will get migrated correctly:

    default-datastore: <default-datastore-name>
    resourcepool-path: "<cluster-name>/Resources/<resource-pool-name>"

    Upstream bug: https://github.com/kubernetes-sigs/vsphere-csi-driver/issues/628

    Rancher issue tracking this bug: https://github.com/rancher/rancher/issues/31105

    Prerequisites

    • vSphere CSI Migration requires vSphere 7.0u1. In order to be able to manage existing in-tree vSphere volumes, upgrade vSphere to 7.0u1.
    • The Kubernetes version must be 1.19 or higher.

    Migration

    1. Install the CPI plugin​

    Before installing CPI, we need to taint all nodes with node.cloudprovider.kubernetes.io/uninitialized=true:NoSchedule.

    This can be done by running the following commands:

    curl -O https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh

    Or:

    wget https://raw.githubusercontent.com/rancher/helm3-charts/56b622f519728378abeddfe95074f1b87ab73b1e/charts/vsphere-cpi/taints.sh
    chmod +x taints.sh
    ./taints.sh <path to kubeconfig if running the command outside the cluster>

    Once all nodes are tainted by the running the script, launch the Helm vSphere CPI chart.

    1. From the Cluster Explorer view, go to the top left dropdown menu and click Apps & Marketplace.
    2. Select the vSphere CPI chart.
    3. Fill out the required vCenter details and click Launch.

    vSphere CPI initializes all nodes with ProviderID, which is needed by the vSphere CSI driver.

    Check if all nodes are initialized with the ProviderID with the following command:

    kubectl describe nodes | grep "ProviderID"

    2. Install the CSI driver​

    1. From the Cluster Explorer view, go to the top left dropdown menu and click Apps & Marketplace.
    2. Select the vSphere CSI chart.
    3. Fill out the required vCenter details and click Launch.
    4. Set Enable CSI Migration to true.
    5. This chart creates a StorageClass with the csi.vsphere.vmware.com as the provisioner. You can provide the URL of the datastore to be used for CSI volume provisioning while creating this StorageClass. The datastore URL can be found in the vSphere client by selecting the datastore and going to the Summary tab. Fill out the details for the StorageClass and click Launch.

    3. Edit the cluster to enable CSI migration feature flags​

    1. While editing the cluster, if the Kubernetes version is less than 1.19, select Kubernetes version 1.19 or higher from the Kubernetes Version dropdown.

    2. For enabling feature flags, click on "Edit as YAML", and add the following under kube-controller and kubelet:

        extra_args:
          feature-gates: "CSIMigration=true,CSIMigrationvSphere=true"

    4. Drain worker nodes​

    Worker nodes must be drained during the upgrade before changing the kubelet and kube-controller-manager args.

    1. Click Edit as Form and then click on "Advanced Options."
    2. Set the field Maximum Worker Nodes Unavailable to count of 1.
    3. To drain the nodes during upgrade, select Drain Nodes > Yes.
    4. Set Force and Delete Local Data to true.
    5. Click Save to upgrade the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html index 77756c08137..26f34e6f5cc 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-a-digitalocean-cluster.html @@ -5,13 +5,13 @@ Creating a DigitalOcean Cluster | Rancher Manager - +
    Version: v2.5

    Creating a DigitalOcean Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in DigitalOcean.

    First, you will set up your DigitalOcean cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in DigitalOcean.

    Then you will create a DigitalOcean cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select DigitalOcean.
    5. Enter your Digital Ocean credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for DigitalOcean will allow Rancher to provision new nodes in DigitalOcean. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for DigitalOcean. For help filling out the form, refer to DigitalOcean Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    1. From the Clusters page, click Add Cluster.
    2. Choose DigitalOcean.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. Add one or more node pools to your cluster. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.
    7. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html index fc4b9f8b165..e2039b17b6d 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.html @@ -5,13 +5,13 @@ Creating an Amazon EC2 Cluster | Rancher Manager - +
    Version: v2.5

    Creating an Amazon EC2 Cluster

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in Amazon EC2.

    First, you will set up your EC2 cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in EC2.

    Then you will create an EC2 cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    Prerequisites​

    Creating an EC2 Cluster

    The steps to create a cluster differ based on your Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials and information from EC2
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select Amazon.
    5. In the Region field, select the AWS region where your cluster nodes will be located.
    6. Enter your AWS EC2 Access Key and Secret Key.
    7. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials and information from EC2​

    Creating a node template for EC2 will allow Rancher to provision new nodes in EC2. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for EC2. For help filling out the form, refer to EC2 Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Add one or more node pools to your cluster. For more information about node pools, see this section.

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    1. From the Clusters page, click Add Cluster.
    2. Choose Amazon EC2.
    3. Enter a Cluster Name.
    4. Create a node pool for each Kubernetes role. For each node pool, choose a node template that you created. For more information about node pools, including best practices for assigning Kubernetes roles to them, see this section.
    5. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    6. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. Refer to Selecting Cloud Providers to configure the Kubernetes Cloud Provider. For help configuring the cluster, refer to the RKE cluster configuration reference.
    7. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    IAM Policies

    Example IAM Policy​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy with PassRole​

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": [
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:Describe*",
                    "ec2:ImportKeyPair",
                    "ec2:CreateKeyPair",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "ec2:DeleteKeyPair",
                    "ec2:ModifyInstanceMetadataOptions"
                ],
                "Resource": "*"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": [
                    "iam:PassRole",
                    "ec2:RunInstances"
                ],
                "Resource": [
                    "arn:aws:ec2:REGION::image/ami-*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:placement-group/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:subnet/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:key-pair/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:network-interface/*",
                    "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:security-group/*",
                    "arn:aws:iam::AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME"
                ]
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "ec2:RebootInstances",
                    "ec2:TerminateInstances",
                    "ec2:StartInstances",
                    "ec2:StopInstances"
                ],
                "Resource": "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*"
            }
        ]
    }

    Example IAM Policy to allow encrypted EBS volumes​

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "kms:Decrypt",
            "kms:GenerateDataKeyWithoutPlaintext",
            "kms:Encrypt",
            "kms:DescribeKey",
            "kms:CreateGrant",
            "ec2:DetachVolume",
            "ec2:AttachVolume",
            "ec2:DeleteSnapshot",
            "ec2:DeleteTags",
            "ec2:CreateTags",
            "ec2:CreateVolume",
            "ec2:DeleteVolume",
            "ec2:CreateSnapshot"
          ],
          "Resource": [
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:volume/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:instance/*",
            "arn:aws:ec2:REGION:AWS_ACCOUNT_ID:snapshot/*",
            "arn:aws:kms:REGION:AWS_ACCOUNT_ID:key/KMS_KEY_ID"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeInstances",
            "ec2:DescribeTags",
            "ec2:DescribeVolumes",
            "ec2:DescribeSnapshots"
          ],
          "Resource": "*"
        }
      ]
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html index 90894e91230..e71af6600ee 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-azure-cluster.html @@ -5,13 +5,13 @@ Creating an Azure Cluster | Rancher Manager - +
    Version: v2.5

    Creating an Azure Cluster

    In this section, you'll learn how to install an RKE Kubernetes cluster in Azure through Rancher.

    First, you will set up your Azure cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision new nodes in Azure.

    Then you will create an Azure cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    Warning: When the Rancher RKE cluster is running in Azure and has an Azure load balancer in front, the outbound flow will fail. The workaround for this problem is as follows:

    • Terminate the SSL/TLS on the internal load balancer
    • Use the L7 load balancer

    For more information, refer to the documentation on Azure load balancer limitations.

    For more information on configuring the Kubernetes cluster that Rancher will install on the Azure nodes, refer to the RKE cluster configuration reference.

    For more information on configuring Azure node templates, refer to the Azure node template configuration reference.

    Preparation in Azure

    Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription.

    To do this, we will first create a new Azure service principal (SP) in Azure Active Directory (AD), which, in Azure, is an application user who has permission to manage Azure resources.

    The following is a template az cli script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope:

    az ad sp create-for-rbac \
      --name="<Rancher ServicePrincipal name>" \
      --role="Contributor" \
      --scopes="/subscriptions/<subscription Id>"

    The creation of this service principal returns three pieces of identification information, The application ID, also called the client ID, The client secret, and The tenant ID. This information will be used when you create a node template for Azure.

    Creating an Azure Cluster

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select Azure.
    5. Enter your Azure credentials.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for Azure will allow Rancher to provision new nodes in Azure. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for Azure. For help filling out the form, refer to Azure Node Template Configuration.

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in Azure.

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    1. From the Clusters page, click Add Cluster.
    2. Choose Azure.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices, see this section.
    7. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html index 5706026115a..57016b9f2b6 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/create-credentials.html @@ -5,13 +5,13 @@ Creating Credentials in the vSphere Console | Rancher Manager - +
    Version: v2.5

    Creating Credentials in the vSphere Console

    This section describes how to create a vSphere username and password. You will need to provide these vSphere credentials to Rancher, which allows Rancher to provision resources in vSphere.

    The following table lists the permissions required for the vSphere user account:

    Privilege GroupOperations
    DatastoreAllocateSpace
    Browse
    FileManagement (Low level file operations)
    UpdateVirtualMachineFiles
    UpdateVirtualMachineMetadata
    NetworkAssign
    ResourceAssignVMToPool
    Virtual MachineConfig (All)
    GuestOperations (All)
    Interact (All)
    Inventory (All)
    Provisioning (All)

    The following steps create a role with the required privileges and then assign it to a new user in the vSphere console:

    1. From the vSphere console, go to the Administration page.

    2. Go to the Roles tab.

    3. Create a new role. Give it a name and select the privileges listed in the permissions table above.

    4. Go to the Users and Groups tab.

    5. Create a new user. Fill out the form and then click OK. Make sure to note the username and password, because you will need it when configuring node templates in Rancher.

    6. Go to the Global Permissions tab.

    7. Create a new Global Permission. Add the user you created earlier and assign it the role you created earlier. Click OK.

    Result: You now have credentials that Rancher can use to manipulate vSphere resources.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html index cca9234005e..48bced92619 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/vsphere/provision-kubernetes-clusters-in-vsphere.html @@ -5,13 +5,13 @@ Provisioning Kubernetes Clusters in vSphere | Rancher Manager - +
    Version: v2.5

    Provisioning Kubernetes Clusters in vSphere

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

    First, you will set up your vSphere cloud credentials in Rancher. Then you will use your cloud credentials to create a node template, which Rancher will use to provision nodes in vSphere.

    Then you will create a vSphere cluster in Rancher, and when configuring the new cluster, you will define node pools for it. Each node pool will have a Kubernetes role of etcd, controlplane, or worker. Rancher will install RKE Kubernetes on the new nodes, and it will set up each node with the Kubernetes role defined by the node pool.

    For details on configuring the vSphere node template, refer to the vSphere node template configuration reference.

    For details on configuring RKE Kubernetes clusters in Rancher, refer to the cluster configuration reference.

    Preparation in vSphere​

    This section describes the requirements for setting up vSphere so that Rancher can provision VMs and clusters.

    The node templates are documented and tested with the vSphere Web Services API version 6.5.

    Create Credentials in vSphere​

    Before proceeding to create a cluster, you must ensure that you have a vSphere user with sufficient permissions. When you set up a node template, the template will need to use these vSphere credentials.

    Refer to this how-to guide for instructions on how to create a user in vSphere with the required permissions. These steps result in a username and password that you will need to provide to Rancher, which allows Rancher to provision resources in vSphere.

    Network Permissions​

    It must be ensured that the hosts running the Rancher server are able to establish the following network connections:

    • To the vSphere API on the vCenter server (usually port 443/TCP).
    • To the Host API (port 443/TCP) on all ESXi hosts used to instantiate virtual machines for the clusters (only required when using the ISO creation method).
    • To port 22/TCP and 2376/TCP on the created VMs

    See Node Networking Requirements for a detailed list of port requirements applicable for creating nodes on an infrastructure provider.

    Valid ESXi License for vSphere API Access​

    The free ESXi license does not support API access. The vSphere servers must have a valid or evaluation ESXi license.

    VM-VM Affinity Rules for Clusters with DRS​

    If you have a cluster with DRS enabled, setting up VM-VM Affinity Rules is recommended. These rules allow VMs assigned the etcd and control-plane roles to operate on separate ESXi hosts when they are assigned to different node pools. This practice ensures that the failure of a single physical machine does not affect the availability of those planes.

    Creating a vSphere Cluster​

    The a vSphere cluster is created in Rancher depends on the Rancher version.

    1. Create your cloud credentials
    2. Create a node template with your cloud credentials
    3. Create a cluster with node pools using the node template

    1. Create your cloud credentials​

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. In the Cloud Credential Type field, select VMware vSphere.
    5. Enter your vSphere credentials. For help, refer to Account Access in the node template configuration reference.
    6. Click Create.

    Result: You have created the cloud credentials that will be used to provision nodes in your cluster. You can reuse these credentials for other node templates, or in other clusters.

    2. Create a node template with your cloud credentials​

    Creating a node template for vSphere will allow Rancher to provision new nodes in vSphere. Node templates can be reused for other clusters.

    1. In the Rancher UI, click the user profile button in the upper right corner, and click Node Templates.
    2. Click Add Template.
    3. Fill out a node template for vSphere. For help filling out the form, refer to the vSphere node template configuration reference..

    3. Create a cluster with node pools using the node template​

    Use Rancher to create a Kubernetes cluster in vSphere.

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    1. Navigate to Clusters in the Global view.
    2. Click Add Cluster and select the vSphere infrastructure provider.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Use Cluster Options to choose the version of Kubernetes that will be installed, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For help configuring the cluster, refer to the RKE cluster configuration reference.
    6. If you want to dynamically provision persistent storage or other infrastructure later, you will need to enable the vSphere cloud provider by modifying the cluster YAML file. For details, refer to this section.
    7. Add one or more node pools to your cluster. Each node pool uses a node template to provision new nodes. For more information about node pools, including best practices for assigning Kubernetes roles to the nodes, see this section.
    8. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    • Provision Storage: For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html index b6d155a4e27..58b1bf4ae53 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/azure-storageclass-configuration.html @@ -5,13 +5,13 @@ Configuration for Storage Classes in Azure | Rancher Manager - +
    Version: v2.5

    Configuration for Storage Classes in Azure

    If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster.

    In order to have the Azure platform create the required storage resources, follow these steps:

    1. Configure the Azure cloud provider.

    2. Configure kubectl to connect to your cluster.

    3. Copy the ClusterRole and ClusterRoleBinding manifest for the service account:

      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: system:azure-cloud-provider
      rules:
      - apiGroups: ['']
        resources: ['secrets']
        verbs:     ['get','create']
      ---
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: system:azure-cloud-provider
      roleRef:
        kind: ClusterRole
        apiGroup: rbac.authorization.k8s.io
        name: system:azure-cloud-provider
      subjects:
      - kind: ServiceAccount
        name: persistent-volume-binder
        namespace: kube-system

    4. Create these in your cluster using one of the follow command.

      # kubectl create -f <MANIFEST>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html index cbba9b5061e..fb757546d8e 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/network-requirements-for-host-gateway.html @@ -5,13 +5,13 @@ Networking Requirements for Host Gateway (L2bridge) | Rancher Manager - +
    Version: v2.5

    Networking Requirements for Host Gateway (L2bridge)

    This section describes how to configure custom Windows clusters that are using Host Gateway (L2bridge) mode.

    Disabling Private IP Address Checks​

    If you are using Host Gateway (L2bridge) mode and hosting your nodes on any of the cloud services listed below, you must disable the private IP address checks for both your Linux or Windows hosts on startup. To disable this check for each node, follow the directions provided by each service below.

    ServiceDirections to disable private IP address checks
    Amazon EC2Disabling Source/Destination Checks
    Google GCEEnabling IP Forwarding for Instances (By default, a VM cannot forward a packet originated by another VM)
    Azure VMEnable or Disable IP Forwarding

    Cloud-hosted VM Routes Configuration​

    If you are using the Host Gateway (L2bridge) backend of Flannel, all containers on the same node belong to a private subnet, and traffic routes from a subnet on one node to a subnet on another node through the host network.

    • When worker nodes are provisioned on AWS, virtualization clusters, or bare metal servers, make sure they belong to the same layer 2 subnet. If the nodes don't belong to the same layer 2 subnet, host-gw networking will not work.

    • When worker nodes are provisioned on GCE or Azure, they are not on the same layer 2 subnet. Nodes on GCE and Azure belong to a routable layer 3 network. Follow the instructions below to configure GCE and Azure so that the cloud network knows how to route the host subnets on each node.

    To configure host subnet routing on GCE or Azure, first run the following command to find out the host subnets on each worker node:

    kubectl get nodes -o custom-columns=nodeName:.metadata.name,nodeIP:status.addresses[0].address,routeDestination:.spec.podCIDR

    Then follow the instructions for each cloud provider to configure routing rules for each node:

    ServiceInstructions
    Google GCEFor GCE, add a static route for each node: Adding a Static Route.
    Azure VMFor Azure, create a routing table: Custom Routes: User-defined.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html index 2f3bde3306f..a13cdf98f7f 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/launch-kubernetes-with-rancher/use-windows-clusters/windows-linux-cluster-feature-parity.html @@ -5,13 +5,13 @@ Windows and Linux Cluster Feature Parity | Rancher Manager - +
    Version: v2.5

    Windows and Linux Cluster Feature Parity

    Windows clusters do not share the same feature support as Linux clusters.

    The following chart describes the feature parity between Windows and Linux on Rancher as of Rancher v2.5.8:

    ComponentLinuxWindows
    Distributions
    RKESupportedSupported
    RKE2SupportedTenatively Planned For 2.6.x
    K3SSupportedNot Supported
    EKSSupportedNot Supported
    GKESupportedNot Supported
    AKSSupportedNot Supported
    Rancher Components
    ServerSupportedNot Supported
    AgentSupportedSupported
    FleetSupportedSupported
    EKS OperatorSupportedNot Supported
    AKS OperatorNot SupportedNot Supported
    GKE OperatorNot SupportedNot Supported
    Alerting v1SupportedSupported
    Monitoring v1SupportedSupported
    Logging v1SupportedSupported
    Monitoring/Alerting v2SupportedSupported In 2.5.8+
    Logging v2SupportedSupported In 2.5.8+
    IstioSupportedNot Supported
    Catalog v1SupportedNot Supported
    Catalog v2SupportedNot Supported
    OPASupportedNot Supported
    LonghornSupportedNot Supported
    CIS ScansSupportedNot Supported
    Backup/Restore OperatorSupportedNot Supported
    CNI / Add-ons
    FlannelSupportedSupported
    CanalSupportedNot Supported
    CalicoSupportedTentatively Planned for 2.6.x
    CiliumSupportedNot Supported
    MultusSupportedNot Supported
    TraefikSupportedNot Supported
    NGINX IngressSupportedNot Supported

    For updated information on feature support, you may visit rancher/windows on GitHub.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html index 8e280530c91..8b326179102 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/node-requirements-for-rancher-managed-clusters.html @@ -5,13 +5,13 @@ Node Requirements for Rancher Managed Clusters | Rancher Manager - +
    Version: v2.5

    Node Requirements for Rancher Managed Clusters

    This page describes the requirements for the Rancher managed Kubernetes clusters where your apps and services will be installed. These downstream clusters should be separate from the three-node cluster running Rancher.

    If Rancher is installed on a high-availability Kubernetes cluster, the Rancher server three-node cluster and downstream clusters have different requirements. For Rancher installation requirements, refer to the node requirements in the installation section.

    Operating Systems and Container Runtime Requirements​

    Rancher should work with any modern Linux distribution and any modern Docker version. Linux is required for the etcd and controlplane nodes of all downstream clusters. Worker nodes may run Linux or Windows Server.

    For details on which OS and Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    All supported operating systems are 64-bit x86.

    If you plan to use ARM64, see Running on ARM64 (Experimental).

    For information on how to install Docker, refer to the official Docker documentation.

    Oracle Linux and RHEL Derived Linux Nodes​

    Some distributions of Linux derived from RHEL, including Oracle Linux, may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19, firewalld must be turned off.

    Note: In RHEL 8.4, two extra services are included on the NetworkManager: nm-cloud-setup.service and nm-cloud-setup.timer. These services add a routing table that interferes with the CNI plugin's configuration. If these services are enabled, you must disable them using the command below, and then reboot the node to restore connectivity:

    systemctl disable nm-cloud-setup.service nm-cloud-setup.timer
    reboot

    SUSE Linux Nodes​

    SUSE Linux may have a firewall that blocks all ports by default. In that situation, follow these steps to open the ports needed for adding a host to a custom cluster.

    Flatcar Container Linux Nodes​

    When Launching Kubernetes with Rancher using Flatcar Container Linux nodes, it is required to use the following configuration in the Cluster Config File

    rancher_kubernetes_engine_config:
      network:
        plugin: canal
        options:
          canal_flex_volume_plugin_dir: /opt/kubernetes/kubelet-plugins/volume/exec/nodeagent~uds
          flannel_backend_type: vxlan

      services:
        kube-controller:
          extra_args:
            flex-volume-plugin-dir: /opt/kubernetes/kubelet-plugins/volume/exec/

    It is also required to enable the Docker service, you can enable the Docker service using the following command:

    systemctl enable docker.service

    The Docker service is enabled automatically when using Node Drivers.

    Windows Nodes​

    Nodes with Windows Server must run Docker Enterprise Edition.

    Windows nodes can be used for worker nodes only. See Configuring Custom Clusters for Windows

    Hardware Requirements​

    The hardware requirements for nodes with the worker role mostly depend on your workloads. The minimum to run the Kubernetes node components is 1 CPU (core) and 1GB of memory.

    Regarding CPU and memory, it is recommended that the different planes of Kubernetes clusters (etcd, controlplane, and workers) should be hosted on different nodes so that they can scale separately from each other.

    For hardware recommendations for large Kubernetes clusters, refer to the official Kubernetes documentation on building large clusters.

    For hardware recommendations for etcd clusters in production, refer to the official etcd documentation.

    Networking Requirements​

    For a production cluster, we recommend that you restrict traffic by opening only the ports defined in the port requirements below.

    IPv6 should be disabled at the OS level. Unless you specifically intend to utilize IPv6, you should disable it on your nodes. IPv6 is not yet fully supported and often times it is not enough to disable IPv6 on the NICs to avoid complications.

    The ports required to be open are different depending on how the user cluster is launched. Each of the sections below list the ports that need to be opened for different cluster creation options.

    For a breakdown of the port requirements for etcd nodes, controlplane nodes, and worker nodes in a Kubernetes cluster, refer to the port requirements for the Rancher Kubernetes Engine.

    Details on which ports are used in each situation are found under Downstream Cluster Port Requirements.

    Optional: Security Considerations​

    If you want to provision a Kubernetes cluster that is compliant with the CIS (Center for Internet Security) Kubernetes Benchmark, we recommend to following our hardening guide to configure your nodes before installing Kubernetes.

    For more information on the hardening guide and details on which version of the guide corresponds to your Rancher and Kubernetes versions, refer to the security section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html index d4f5364d89d..94ce29a982e 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.html @@ -5,14 +5,14 @@ Registering Existing Clusters | Rancher Manager - +
    Version: v2.5

    Registering Existing Clusters

    The cluster registration feature replaced the feature to import clusters.

    The control that Rancher has to manage a registered cluster depends on the type of cluster. For details, see Management Capabilities for Registered Clusters.

    Prerequisites​

    Kubernetes Node Roles​

    Registered RKE Kubernetes clusters must have all three node roles - etcd, controlplane and worker. A cluster with only controlplane components cannot be registered in Rancher.

    For more information on RKE node roles, see the best practices.

    Permissions​

    If your existing Kubernetes cluster already has a cluster-admin role defined, you must have this cluster-admin privilege to register the cluster in Rancher.

    In order to apply the privilege, you need to run:

    kubectl create clusterrolebinding cluster-admin-binding \
      --clusterrole cluster-admin \
      --user [USER_ACCOUNT]

    before running the kubectl command to register the cluster.

    By default, GKE users are not given this privilege, so you will need to run the command before registering GKE clusters. To learn more about role-based access control for GKE, please click here.

    If you are registering a K3s cluster, make sure the cluster.yml is readable. It is protected by default. For details, refer to Configuring a K3s cluster to enable importation to Rancher.

    EKS Clusters​

    EKS clusters must have at least one managed node group to be imported into Rancher or provisioned from Rancher successfully.

    Registering a Cluster​

    1. From the Clusters page, click Add Cluster.
    2. Under Register an existing Kubernetes cluster, click the type of Kubernetes cluster you want to register.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. For Rancher v2.5.6+, use Agent Environment Variables under Cluster Options to set environment variables for rancher cluster agent. The environment variables can be set using key value pairs. If rancher agent requires use of proxy to communicate with Rancher server, HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables can be set using agent environment variables.
    6. Click Create.
    7. The prerequisite for cluster-admin privileges is shown (see Prerequisites above), including an example command to fulfil the prerequisite.
    8. Copy the kubectl command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run kubectl get nodes to verify before running the command shown in Rancher.
    9. If you are using self signed certificates, you will receive the message certificate signed by unknown authority. To work around this validation, copy the command starting with curl displayed in Rancher to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import.
    10. When you finish running the command(s) on your node, click Done.

    Result:

    • Your cluster is registered and assigned a state of Pending. Rancher is deploying resources to manage your cluster.
    • You can access your cluster after its state is updated to Active.
    • Active clusters are assigned two Projects: Default (containing the namespace default) and System (containing the namespaces cattle-system, ingress-nginx, kube-public and kube-system, if present).

    Note: You can not re-register a cluster that is currently active in a Rancher setup.

    Configuring a K3s Cluster to Enable Registration in Rancher​

    The K3s server needs to be configured to allow writing to the kubeconfig file.

    This can be accomplished by passing --write-kubeconfig-mode 644 as a flag during installation:

    $ curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644

    The option can also be specified using the environment variable K3S_KUBECONFIG_MODE:

    $ curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s -

    Configuring an Imported EKS Cluster with Terraform​

    You should define only the minimum fields that Rancher requires when importing an EKS cluster with Terraform. This is important as Rancher will overwrite what was in the EKS cluster with any config that the user has provided.

    Warning: Even a small difference between the current EKS cluster and a user-provided config could have unexpected results.

    The minimum config fields required by Rancher to import EKS clusters with Terraform using eks_config_v2 are as follows:

    • cloud_credential_id
    • name
    • region
    • imported (this field should always be set to true for imported clusters)

    Example YAML configuration for imported EKS clusters:

    resource "rancher2_cluster" "my-eks-to-import" {
      name        = "my-eks-to-import"
      description = "Terraform EKS Cluster"
      eks_config_v2 {
        cloud_credential_id = rancher2_cloud_credential.aws.id
        name                = var.aws_eks_name
        region              = var.aws_region
        imported            = true
      }
    }

    Management Capabilities for Registered Clusters​

    The control that Rancher has to manage a registered cluster depends on the type of cluster.

    Changes in v2.5.8​

    Greater management capabilities are now available for registered GKE clusters. The same configuration options are available for registered GKE clusters as for the GKE clusters created through the Rancher UI.

    ### Features for All Registered Clusters

    After registering a cluster, the cluster owner can:

    ### Additional Features for Registered K3s Clusters

    K3s is a lightweight, fully compliant Kubernetes distribution.

    When a K3s cluster is registered in Rancher, Rancher will recognize it as K3s. The Rancher UI will expose the features for all registered clusters, in addition to the following features for editing and upgrading the cluster:

    • The ability to upgrade the K3s version
    • The ability to configure the maximum number of nodes that will be upgraded concurrently
    • The ability to see a read-only version of the K3s cluster's configuration arguments and environment variables used to launch each node in the cluster

    Additional Features for Registered EKS and GKE Clusters​

    Registering an Amazon EKS cluster or GKE cluster allows Rancher to treat it as though it were created in Rancher.

    Amazon EKS clusters and GKE clusters can now be registered in Rancher. For the most part, these registered clusters are treated the same way as clusters created in the Rancher UI, except for deletion.

    When you delete an EKS cluster or GKE cluster that was created in Rancher, the cluster is destroyed. When you delete a cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.

    The capabilities for registered clusters are listed in the table on this page.

    Configuring K3s Cluster Upgrades​

    It is a Kubernetes best practice to back up the cluster before upgrading. When upgrading a high-availability K3s cluster with an external database, back up the database in whichever way is recommended by the relational database provider.

    The concurrency is the maximum number of nodes that are permitted to be unavailable during an upgrade. If number of unavailable nodes is larger than the concurrency, the upgrade will fail. If an upgrade fails, you may need to repair or remove failed nodes before the upgrade can succeed.

    • Controlplane concurrency: The maximum number of server nodes to upgrade at a single time; also the maximum unavailable server nodes
    • Worker concurrency: The maximum number worker nodes to upgrade at the same time; also the maximum unavailable worker nodes

    In the K3s documentation, controlplane nodes are called server nodes. These nodes run the Kubernetes master, which maintains the desired state of the cluster. In K3s, these controlplane nodes have the capability to have workloads scheduled to them by default.

    Also in the K3s documentation, nodes with the worker role are called agent nodes. Any workloads or pods that are deployed in the cluster can be scheduled to these nodes by default.

    Debug Logging and Troubleshooting for Registered K3s Clusters​

    Nodes are upgraded by the system upgrade controller running in the downstream cluster. Based on the cluster configuration, Rancher deploys two plans to upgrade K3s nodes: one for controlplane nodes and one for workers. The system upgrade controller follows the plans and upgrades the nodes.

    To enable debug logging on the system upgrade controller deployment, edit the configmap to set the debug environment variable to true. Then restart the system-upgrade-controller pod.

    Logs created by the system-upgrade-controller can be viewed by running this command:

    kubectl logs -n cattle-system system-upgrade-controller

    The current status of the plans can be viewed with this command:

    kubectl get plans -A -o yaml

    If the cluster becomes stuck in upgrading, restart the system-upgrade-controller.

    To prevent issues when upgrading, the Kubernetes upgrade best practices should be followed.

    Annotating Registered Clusters​

    For all types of registered Kubernetes clusters except for K3s Kubernetes clusters, Rancher doesn't have any information about how the cluster is provisioned or configured.

    Therefore, when Rancher registers a cluster, it assumes that several capabilities are disabled by default. Rancher assumes this in order to avoid exposing UI options to the user even when the capabilities are not enabled in the registered cluster.

    However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster.

    By annotating a registered cluster, it is possible to indicate to Rancher that a cluster was given a pod security policy, or another capability, outside of Rancher.

    This example annotation indicates that a pod security policy is enabled:

    "capabilities.cattle.io/pspEnabled": "true"

    The following annotation indicates Ingress capabilities. Note that that the values of non-primitive objects need to be JSON encoded, with quotations escaped.

    "capabilities.cattle.io/ingressCapabilities": "[
      {
        "customDefaultBackend":true,
        "ingressProvider":"asdf"
      }
    ]"

    These capabilities can be annotated for the cluster:

    • ingressCapabilities
    • loadBalancerCapabilities
    • nodePoolScalingSupported
    • nodePortRange
    • pspEnabled
    • taintSupport

    All the capabilities and their type definitions can be viewed in the Rancher API view, at [Rancher Server URL]/v3/schemas/capabilities.

    To annotate a registered cluster,

    1. Go to the cluster view in Rancher and select ⋮ > Edit.
    2. Expand the Labels & Annotations section.
    3. Click Add Annotation.
    4. Add an annotation to the cluster with the format capabilities/<capability>: <value> where value is the cluster capability that will be overridden by the annotation. In this scenario, Rancher is not aware of any capabilities of the cluster until you add the annotation.
    5. Click Save.

    Result: The annotation does not give the capabilities to the cluster, but it does indicate to Rancher that the cluster has those capabilities.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html index 2d0ec4b51c3..3096b8f94c6 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/aks.html @@ -5,14 +5,14 @@ Creating an AKS Cluster | Rancher Manager - +
    Version: v2.5

    Creating an AKS Cluster

    You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS).

    Prerequisites in Microsoft Azure​

    Note Deploying to AKS will incur charges.

    To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the AKS documentation.

    Before creating the service principal, you need to obtain the following information from the Microsoft Azure Portal:

    • Your subscription ID
    • Your tenant ID
    • An app ID (also called a client ID)
    • Client secret
    • A resource group

    The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal.

    Setting Up the Service Principal with the Azure Command Line Tool​

    You can create the service principal by running this command:

    az ad sp create-for-rbac --skip-assignment

    The result should show information about the new service principal:

    {
      "appId": "xxxx--xxx",
      "displayName": "<SERVICE-PRINCIPAL-NAME>",
      "name": "http://<SERVICE-PRINCIPAL-NAME>",
      "password": "<SECRET>",
      "tenant": "<TENANT NAME>"
    }

    You also need to add roles to the service principal so that it has privileges for communication with the AKS API. It also needs access to create and list virtual networks.

    Below is an example command for assigning the Contributor role to a service principal. Contributors can manage anything on AKS but cannot give access to others:

    az role assignment create \
      --assignee $appId \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    You can also create the service principal and give it Contributor privileges by combining the two commands into one. In this command, the scope needs to provide a full path to an Azure resource:

    az ad sp create-for-rbac \
      --scope /subscriptions/$<SUBSCRIPTION-ID>/resourceGroups/$<GROUP> \
      --role Contributor

    Setting Up the Service Principal from the Azure Portal​

    You can also follow these instructions to set up a service principal and give it role-based access from the Azure Portal.

    1. Go to the Microsoft Azure Portal home page.

    2. Click Azure Active Directory.

    3. Click App registrations.

    4. Click New registration.

    5. Enter a name. This will be the name of your service principal.

    6. Optional: Choose which accounts can use the service principal.

    7. Click Register.

    8. You should now see the name of your service principal under Azure Active Directory > App registrations.

    9. Click the name of your service principal. Take note of the tenant ID and application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click Certificates & secrets.

    10. Click New client secret.

    11. Enter a short description, pick an expiration time, and click Add. Take note of the client secret so that you can use it when provisioning the AKS cluster.

    Result: You have created a service principal and you should be able to see it listed in the Azure Active Directory section under App registrations. You still need to give the service principal access to AKS.

    To give role-based access to your service principal,

    1. Click All Services in the left navigation bar. Then click Subscriptions.

    2. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster.

    3. Click Access Control (IAM).

    4. In the Add role assignment section, click Add.

    5. In the Role field, select a role that will have access to AKS. For example, you can use the Contributor role, which has permission to manage everything except for giving access to other users.

    6. In the Assign access to field, select Azure AD user, group, or service principal.

    7. In the Select field, select the name of your service principal and click Save.

    Result: Your service principal now has access to AKS.

    Create the AKS Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. From the Clusters page, click Add Cluster.

    2. Choose Azure AKS.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Use your subscription ID, tenant ID, client ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:

    • Tenant ID: To get the Tenant ID, you can go to the Azure Portal, then click Azure Active Directory, then click Properties and find the Tenant ID field.
    • Client ID: To get the Client ID, you can go to the Azure Portal, then click Azure Active Directory, then click Enterprise applications. Click All applications. Select your application, click Properties, and copy the application ID.
    • Client secret: If you didn't copy the client secret when creating the service principal, you can get a new one if you go to the app registration detail page, then click Certificates & secrets, then click New client secret.
    • Subscription ID: You can get the subscription ID is available in the portal from All services > Subscriptions.

    1. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options.

    2. Complete the Account Access form using the output from your Service Principal. This information is used to authenticate with Azure.

    3. Use Nodes to provision each node in your cluster and choose a geographical region.

      [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys)

    4. Click Create.


    5. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html index a88268a6448..380205f2933 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/alibaba.html @@ -5,14 +5,14 @@ Creating an Aliyun ACK Cluster | Rancher Manager - +
    Version: v2.5

    Creating an Aliyun ACK Cluster

    You can use Rancher to create a cluster hosted in Alibaba Cloud Kubernetes (ACK). Rancher has already implemented and packaged the cluster driver for ACK, but by default, this cluster driver is inactive. In order to launch ACK clusters, you will need to enable the ACK cluster driver. After enabling the cluster driver, you can start provisioning ACK clusters.

    Prerequisites​

    Note Deploying to ACK will incur charges.

    1. In Aliyun, activate the following services in their respective consoles.

    2. Make sure that the account you will be using to create the ACK cluster has the appropriate permissions. Referring to the official Alibaba Cloud documentation about Role authorization and Use the Container Service console as a RAM user for details.

    3. In Alibaba Cloud, create an access key.

    4. In Alibaba Cloud, create an SSH key pair. This key is used to access nodes in the Kubernetes cluster.

    Create an ACK Cluster​

    1. From the Clusters page, click Add Cluster.

    2. Choose Alibaba ACK.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Configure Account Access for the ACK cluster. Choose the geographical region in which to build your cluster, and input the access key that was created as part of the prerequisite steps.

    6. Click Next: Configure Cluster, then choose cluster type, the version of Kubernetes and the availability zone.

    7. If you choose Kubernetes as the cluster type, Click Next: Configure Master Nodes, then complete the Master Nodes form.

    8. Click Next: Configure Worker Nodes, then complete the Worker Nodes form.

    9. Review your options to confirm they're correct. Then click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html index 20b12dc4280..2815d34befe 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/gke.html @@ -5,7 +5,7 @@ Managing GKE Clusters | Rancher Manager - + @@ -14,7 +14,7 @@ Deploying to GKE will incur charges.

    1. Create a Cloud Credential​

    1. In the upper right corner, click the user profile dropdown menu and click Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for your Google cloud credentials.
    4. In the Cloud Credential Type field, select Google.
    5. In the Service Account text box, paste your service account private key JSON, or upload the JSON file.
    6. Click Create.

    Result: You have created credentials that Rancher will use to provision the new GKE cluster.

    2. Create the GKE Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. From the Clusters page, click Add Cluster.
    2. Under With a hosted Kubernetes provider, click Google GKE.
    3. Enter a Cluster Name.
    4. Optional: Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Optional: Add Kubernetes labels or annotations to the cluster.
    6. Enter your Google project ID and your Google cloud credentials.
    7. Fill out the rest of the form. For help, refer to the GKE cluster configuration reference.
    8. Click Create.

    Result: You have successfully deployed a GKE cluster.

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Private Clusters​

    Private GKE clusters are supported. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see this section.

    Configuration Reference​

    For details on configuring GKE clusters in Rancher, see this page.

    Updating Kubernetes Version​

    The Kubernetes version of a cluster can be upgraded to any version available in the region or zone fo the GKE cluster. Upgrading the master Kubernetes version does not automatically upgrade worker nodes. Nodes can be upgraded independently.

    Note GKE has removed basic authentication in 1.19+. In order to upgrade a cluster to 1.19+, basic authentication must be disabled in the Google Cloud. Otherwise, an error will appear in Rancher when an upgrade to 1.19+ is attempted. You can follow the Google documentation. After this, the Kubernetes version can be updated to 1.19+ via Rancher.

    Syncing​

    The GKE provisioner can synchronize the state of a GKE cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

    For information on configuring the refresh interval, see this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html index cc5286414f4..f467fb44c8c 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/huawei.html @@ -5,14 +5,14 @@ Creating a Huawei CCE Cluster | Rancher Manager - +
    Version: v2.5

    Creating a Huawei CCE Cluster

    You can use Rancher to create a cluster hosted in Huawei Cloud Container Engine (CCE). Rancher has already implemented and packaged the cluster driver for CCE, but by default, this cluster driver is inactive. In order to launch CCE clusters, you will need to enable the CCE cluster driver. After enabling the cluster driver, you can start provisioning CCE clusters.

    Prerequisites in Huawei​

    Note Deploying to CCE will incur charges.

    1. Find your project ID in Huawei CCE portal. See the CCE documentation on how to manage your projects.

    2. Create an Access Key ID and Secret Access Key.

    Limitations​

    Huawei CCE service doesn't support the ability to create clusters with public access through their API. You are required to run Rancher in the same VPC as the CCE clusters that you want to provision.

    Create the CCE Cluster​

    1. From the Clusters page, click Add Cluster.
    2. Choose Huawei CCE.
    3. Enter a Cluster Name.
    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.
    5. Enter Project Id, Access Key ID as Access Key and Secret Access Key Secret Key. Then Click Next: Configure cluster. Fill in the cluster configuration. For help filling out the form, refer to Huawei CCE Configuration.
    6. Fill the following node configuration of the cluster. For help filling out the form, refer to Node Configuration.
    7. Click Create to create the CCE cluster.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    Huawei CCE Configuration​

    SettingsDescription
    Cluster TypeWhich type or node you want to include into the cluster, VirtualMachine or BareMetal.
    DescriptionThe description of the cluster.
    Master VersionThe Kubernetes version.
    Management Scale CountThe max node count of the cluster. The options are 50, 200 and 1000. The larger of the scale count, the more the cost.
    High AvailabilityEnable master node high availability. The cluster with high availability enabled will have more cost.
    Container Network ModeThe network mode used in the cluster. overlay_l2 and vpc-router is supported in VirtualMachine type and underlay_ipvlan is supported in BareMetal type
    Container Network CIDRNetwork CIDR for the cluster.
    VPC NameThe VPC name which the cluster is going to deploy into. Rancher will create one if it is blank.
    Subnet NameThe Subnet name which the cluster is going to deploy into. Rancher will create one if it is blank.
    External ServerThis option is reserved for the future we can enable CCE cluster public access via API. For now, it is always disabled.
    Cluster LabelThe labels for the cluster.
    Highway SubnetThis option is only supported in BareMetal type. It requires you to select a VPC with high network speed for the bare metal machines.

    Note: If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure.

    Node Configuration​

    SettingsDescription
    ZoneThe available zone at where the node(s) of the cluster is deployed.
    Billing ModeThe bill mode for the cluster node(s). In VirtualMachine type, only Pay-per-use is supported. in BareMetal, you can choose Pay-per-use or Yearly/Monthly.
    Validity PeriodThis option only shows in Yearly/Monthly bill mode. It means how long you want to pay for the cluster node(s).
    Auto RenewThis option only shows in Yearly/Monthly bill mode. It means that the cluster node(s) will renew the Yearly/Monthly payment automatically or not.
    Data Volume TypeData volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Data Volume SizeData volume size for the cluster node(s)
    Root Volume TypeRoot volume type for the cluster node(s). SATA, SSD or SAS for this option.
    Root Volume SizeRoot volume size for the cluster node(s)
    Node FlavorThe node flavor of the cluster node(s). The flavor list in Rancher UI is fetched from Huawei Cloud. It includes all the supported node flavors.
    Node CountThe node count of the cluster
    Node Operating SystemThe operating system for the cluster node(s). Only EulerOS 2.2 and CentOS 7.4 are supported right now.
    SSH Key NameThe ssh key for the cluster node(s)
    EIPThe public IP options for the cluster node(s). Disabled means that the cluster node(s) are not going to bind a public IP. Create EIP means that the cluster node(s) will bind one or many newly created Eips after provisioned and more options will be shown in the UI to set the to-create EIP parameters. And Select Existed EIP means that the node(s) will bind to the EIPs you select.
    EIP CountThis option will only be shown when Create EIP is selected. It means how many EIPs you want to create for the node(s).
    EIP TypeThis option will only be shown when Create EIP is selected. The options are 5_bgp and 5_sbgp.
    EIP Share TypeThis option will only be shown when Create EIP is selected. The only option is PER.
    EIP Charge ModeThis option will only be shown when Create EIP is selected. The options are pay by BandWidth and pay by Traffic.
    EIP Bandwidth SizeThis option will only be shown when Create EIP is selected. The BandWidth of the EIPs.
    Authentication ModeIt means enabling RBAC or also enabling Authenticating Proxy. If you select Authenticating Proxy, the certificate which is used for authenticating proxy will be also required.
    Node LabelThe labels for the cluster node(s). Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html index 910fc2ce711..027df4d2838 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/tencent.html @@ -5,14 +5,14 @@ Creating a Tencent TKE Cluster | Rancher Manager - +
    Version: v2.5

    Creating a Tencent TKE Cluster

    You can use Rancher to create a cluster hosted in Tencent Kubernetes Engine (TKE). Rancher has already implemented and packaged the cluster driver for TKE, but by default, this cluster driver is inactive. In order to launch TKE clusters, you will need to enable the TKE cluster driver. After enabling the cluster driver, you can start provisioning TKE clusters.

    Prerequisites in Tencent​

    Note Deploying to TKE will incur charges.

    1. Make sure that the account you will be using to create the TKE cluster has the appropriate permissions by referring to the Cloud Access Management documentation for details.

    2. Create a Cloud API Secret ID and Secret Key.

    3. Create a Private Network and Subnet in the region that you want to deploy your Kubernetes cluster.

    4. Create a SSH key pair. This key is used to access the nodes in the Kubernetes cluster.

    Create a TKE Cluster​

    1. From the Clusters page, click Add Cluster.

    2. Choose Tencent TKE.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Configure Account Access for the TKE cluster. Complete each drop-down and field using the information obtained in Prerequisites.

      OptionDescription
      RegionFrom the drop-down chooses the geographical region in which to build your cluster.
      Secret IDEnter the Secret ID that you obtained from the Tencent Cloud Console.
      Secret KeyEnter the Secret key that you obtained from Tencent Cloud Console.

    6. Click Next: Configure Cluster to set your TKE cluster configurations.

      OptionDescription
      Kubernetes VersionThe TKE only supports Kubernetes version 1.10.5 now.
      Node CountEnter the amount of worker node you want to purchase for your Kubernetes cluster, up to 100.
      VPCSelect the VPC name that you have created in the Tencent Cloud Console.
      Container Network CIDREnter the CIDR range of your Kubernetes cluster, you may check the available range of the CIDR in the VPC service of the Tencent Cloud Console. Default to 172.16.0.0/16.

      Note: If you are editing the cluster in the cluster.yml instead of the Rancher UI, note that, cluster configuration directives must be nested under the rancher_kubernetes_engine_config directive in cluster.yml. For more information, refer to the section on the config file structure in Rancher v2.3.0+.

    7. Click Next: Select Instance Type to choose the instance type that will use for your TKE cluster.

      OptionDescription
      Availability ZoneChoose the availability zone of the VPC region.
      SubnetSelect the Subnet that you have created within the VPC, and add a new one if you don't have it in the chosen availability zone.
      Instance TypeFrom the drop-down chooses the VM instance type that you want to use for the TKE cluster, default to S2.MEDIUM4 (CPU 2 Memory 4 GiB).

    8. Click Next: Configure Instance to configure the VM instance that will use for your TKE cluster.

      OptionDescription
      Operating SystemThe name of the operating system, currently supports Centos7.2x86_64 or ubuntu16.04.1 LTSx86_64
      Security GroupSecurity group ID, default does not bind any security groups.
      Root Disk TypeSystem disk type. System disk type restrictions are detailed in the CVM instance configuration.
      Root Disk SizeSystem disk size. Linux system adjustment range is 20 - 50G, step size is 1.
      Data Disk TypeData disk type, default value to the SSD cloud drive
      Data Disk SizeData disk size (GB), the step size is 10
      Band Width TypeType of bandwidth, PayByTraffic or PayByHour
      Band WidthPublic network bandwidth (Mbps)
      Key PairKey id, after associating the key can be used to logging to the VM node

    9. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html index a2a274612c4..237afd08662 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/configmaps.html @@ -5,13 +5,13 @@ ConfigMaps | Rancher Manager - +
    Version: v2.5

    ConfigMaps

    While most types of Kubernetes secrets store sensitive information, ConfigMaps store general configuration information, such as a group of config files. Because ConfigMaps don't store sensitive information, they can be updated automatically, and therefore don't require their containers to be restarted following update (unlike most secret types, which require manual updates and a container restart to take effect).

    ConfigMaps accept key value pairs in common string formats, like config files or JSON blobs. After you upload a config map, any workload can reference it as either an environment variable or a volume mount.

    Note: ConfigMaps can only be applied to namespaces and not projects.

    1. From the Global view, select the project containing the namespace that you want to add a ConfigMap to.

    2. From the main menu, select Resources > Config Maps. Click Add Config Map.

    3. Enter a Name for the Config Map.

      Note: Kubernetes classifies ConfigMaps as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your ConfigMaps must have a unique name among the other certificates, registries, and secrets within your workspace.

    4. Select the Namespace you want to add Config Map to. You can also add a new namespace on the fly by clicking Add to a new namespace.

    5. From Config Map Values, click Add Config Map Value to add a key value pair to your ConfigMap. Add as many values as you need.

    6. Click Save.

      Note: Don't use ConfigMaps to store sensitive data use a secret.

      Tip: You can add multiple key value pairs to the ConfigMap by copying and pasting.

    Result: Your ConfigMap is added to the namespace. You can view it in the Rancher UI from the Resources > Config Maps view.

    What's Next?​

    Now that you have a ConfigMap added to a namespace, you can add it to a workload that you deploy from the namespace of origin. You can use the ConfigMap to specify information for you application to consume, such as:

    • Application environment variables.
    • Specifying parameters for a Volume mounted to the workload.

    For more information on adding ConfigMaps to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html index bd26b2980ea..daa04c9aa29 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/create-services.html @@ -5,14 +5,14 @@ Service Discovery | Rancher Manager - +
    Version: v2.5

    Service Discovery

    For every workload created, a complementing Service Discovery entry is created. This Service Discovery entry enables DNS resolution for the workload's pods using the following naming convention: <workload>.<namespace>.svc.cluster.local.

    However, you also have the option of creating additional Service Discovery records. You can use these additional records so that a given namespace resolves with one or more external IP addresses, an external hostname, an alias to another DNS record, other workloads, or a set of pods that match a selector that you create.

    1. From the Global view, open the project that you want to add a DNS record to.

    2. Click Resources in the main navigation bar. Click the Service Discovery tab. Then click Add Record.

    3. Enter a Name for the DNS record. This name is used for DNS resolution.

    4. Select a Namespace from the drop-down list. Alternatively, you can create a new namespace on the fly by clicking Add to a new namespace.

    5. Select one of the Resolves To options to route requests to the DNS record.

      1. One or more external IP addresses

        Enter an IP address in the Target IP Addresses field. Add more IP addresses by clicking Add Target IP.

      2. An external hostname

        Enter a Target Hostname.

      3. Alias of another DNS record's value

        Click Add Target Record and select another DNS record from the Value drop-down.

      4. One or more workloads

        Click Add Target Workload and select another workload from the Value drop-down.

      5. The set of pods which match a selector

        Enter key value pairs of label selectors to create a record for all pods that match your parameters.

    6. Click Create

    Result: A new DNS record is created.

    • You can view the record by from the project's Service Discovery tab.
    • When you visit the new DNS name for the new record that you created (<recordname>.<namespace>.svc.cluster.local), it resolves the chosen namespace.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html index 6ea4bc55ed1..453a99b700d 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/encrypt-http-communication.html @@ -5,13 +5,13 @@ Encrypting HTTP Communication | Rancher Manager - +
    Version: v2.5

    Encrypting HTTP Communication

    When you create an ingress within Rancher/Kubernetes, you must provide it with a secret that includes a TLS private key and certificate, which are used to encrypt and decrypt communications that come through the ingress. You can make certificates available for ingress use by navigating to its project or namespace, and then uploading the certificate. You can then add the certificate to the ingress deployment.

    Add SSL certificates to either projects, namespaces, or both. A project scoped certificate will be available in all its namespaces.

    Prerequisites: You must have a TLS private key and certificate available to upload.

    1. From the Global view, select the project where you want to deploy your ingress.

    2. From the main menu, select Resources > Secrets > Certificates. Click Add Certificate.

    3. Enter a Name for the certificate.

      Note: Kubernetes classifies SSL certificates as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your SSL certificate must have a unique name among the other certificates, registries, and secrets within your project/workspace.

    4. Select the Scope of the certificate.

      • Available to all namespaces in this project: The certificate is available for any deployment in any namespaces in the project.

      • Available to a single namespace: The certificate is only available for the deployments in one namespace. If you choose this option, select a Namespace from the drop-down list or click Add to a new namespace to add the certificate to a namespace you create on the fly.

    5. From Private Key, either copy and paste your certificate's private key into the text box (include the header and footer), or click Read from a file to browse to the private key on your file system. If possible, we recommend using Read from a file to reduce likelihood of error.

      Private key files end with an extension of .key.

    6. From Certificate, either copy and paste your certificate into the text box (include the header and footer), or click Read from a file to browse to the certificate on your file system. If possible, we recommend using Read from a file to reduce likelihood of error.

      Certificate files end with an extension of .crt.

    Result: Your certificate is added to the project or namespace. You can now add it to deployments.

    • If you added an SSL certificate to the project, the certificate is available for deployments created in any project namespace.
    • If you added an SSL certificate to a namespace, the certificate is available only for deployments in that namespace.
    • Your certificate is added to the Resources > Secrets > Certificates view.

    What's Next?​

    Now you can add the certificate when launching an ingress within the current project or namespace. For more information, see Adding Ingress.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html index f2bb71d4463..025a53f73fe 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/about-hpas.html @@ -5,13 +5,13 @@ Background Information on HPAs | Rancher Manager - +
    Version: v2.5

    Background Information on HPAs

    The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down. This section provides explanation on how HPA works with Kubernetes.

    Why Use Horizontal Pod Autoscaler?​

    Using HPA, you can automatically scale the number of pods within a replication controller, deployment, or replica set up or down. HPA automatically scales the number of pods that are running for maximum efficiency. Factors that affect the number of pods include:

    • A minimum and maximum number of pods allowed to run, as defined by the user.
    • Observed CPU/memory use, as reported in resource metrics.
    • Custom metrics provided by third-party metrics application like Prometheus, Datadog, etc.

    HPA improves your services by:

    • Releasing hardware resources that would otherwise be wasted by an excessive number of pods.
    • Increase/decrease performance as needed to accomplish service level agreements.

    How HPA Works​

    HPA Schema

    HPA is implemented as a control loop, with a period controlled by the kube-controller-manager flags below:

    FlagDefaultDescription
    --horizontal-pod-autoscaler-sync-period30sHow often HPA audits resource/custom metrics in a deployment.
    --horizontal-pod-autoscaler-downscale-delay5m0sFollowing completion of a downscale operation, how long HPA must wait before launching another downscale operations.
    --horizontal-pod-autoscaler-upscale-delay3m0sFollowing completion of an upscale operation, how long HPA must wait before launching another upscale operation.

    For full documentation on HPA, refer to the Kubernetes Documentation.

    Horizontal Pod Autoscaler API Objects​

    HPA is an API resource in the Kubernetes autoscaling API group. The current stable version is autoscaling/v1, which only includes support for CPU autoscaling. To get additional support for scaling based on memory and custom metrics, use the beta version instead: autoscaling/v2beta1.

    For more information about the HPA API object, see the HPA GitHub Readme.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html index 540e6577be0..64fa0a62238 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-kubectl.html @@ -5,7 +5,7 @@ Managing HPAs with kubectl | Rancher Manager - + @@ -22,7 +22,7 @@ I0724 10:18:45.699620 1 api.go:93] Response Body: {"status":&quo I0724 10:18:45.699939 1 wrap.go:42] GET /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/%2A/fs_read?labelSelector=app%3Dhello-world: (12.431262ms) 200 [[kube-controller-manager/v1.10.1 (linux/amd64) kubernetes/d4ab475/system:serviceaccount:kube-system:horizontal-pod-autoscaler] 10.42.0.0:24268] I0724 10:18:51.727845 1 request.go:836] Request Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1beta1","metadata":{"creationTimestamp":null},"spec":{"nonResourceAttributes":{"path":"/","verb":"get"},"user":"system:anonymous","group":["system:unauthenticated"]},"status":{"allowed":false}} ...

    1. Check that the metrics API is accessible from kubectl.

    • If you are accessing the cluster directly, enter your Server URL in the kubectl config in the following format: https://<Kubernetes_URL>:6443.

      # kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    • If you are accessing the cluster through Rancher, enter your Server URL in the kubectl config in the following format: https://<RANCHER_URL>/k8s/clusters/<CLUSTER_ID>. Add the suffix /k8s/clusters/<CLUSTER_ID> to API path.

      # kubectl get --raw /k8s/clusters/<CLUSTER_ID>/apis/custom.metrics.k8s.io/v1beta1

      If the API is accessible, you should receive output that's similar to what follows.

      API Response

      {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[{"name":"pods/fs_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_rss","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_period","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_read","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_user","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/last_seen","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/tasks_state","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_quota","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/start_time_seconds","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_write","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_cache","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_cfs_throttled_periods","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_working_set_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_udp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes_free","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_inodes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_time_weighted","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failures","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_swap","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_cpu_shares","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_swap_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_io_current","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_failcnt","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_writes_merged","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/network_tcp_usage","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/memory_max_usage_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/spec_memory_reservation_limit_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_load_average_10s","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/cpu_system","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_reads_bytes","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]},{"name":"pods/fs_sector_reads","singularName":"","namespaced":true,"kind":"MetricValueList","verbs":["get"]}]}

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html index 73f299caa72..d01be70d6f8 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/manage-hpas-with-ui.html @@ -5,13 +5,13 @@ Managing HPAs with the Rancher UI | Rancher Manager - +
    Version: v2.5

    Managing HPAs with the Rancher UI

    The Rancher UI supports creating, managing, and deleting HPAs. You can configure CPU or memory usage as the metric that the HPA uses to scale.

    If you want to create HPAs that scale based on other metrics than CPU and memory, refer to Configuring HPA to Scale Using Custom Metrics with Prometheus.

    Creating an HPA​

    1. From the Global view, open the project that you want to deploy a HPA to.

    2. Click Resources > HPA.

    3. Click Add HPA.

    4. Enter a Name for the HPA.

    5. Select a Namespace for the HPA.

    6. Select a Deployment as scale target for the HPA.

    7. Specify the Minimum Scale and Maximum Scale for the HPA.

    8. Configure the metrics for the HPA. You can choose memory or CPU usage as the metric that will cause the HPA to scale the service up or down. In the Quantity field, enter the percentage of the workload's memory or CPU usage that will cause the HPA to scale the service. To configure other HPA metrics, including metrics available from Prometheus, you need to manage HPAs using kubectl.

    9. Click Create to create the HPA.

    Result: The HPA is deployed to the chosen namespace. You can view the HPA's status from the project's Resources > HPA view.

    Get HPA Metrics and Status​

    1. From the Global view, open the project with the HPAs you want to look at.

    2. Click Resources > HPA. The HPA tab shows the number of current replicas.

    3. For more detailed metrics and status of a specific HPA, click the name of the HPA. This leads to the HPA detail page.

    Deleting an HPA​

    1. From the Global view, open the project that you want to delete an HPA from.

    2. Click Resources > HPA.

    3. Find the HPA which you would like to delete.

    4. Click ⋮ > Delete.

    5. Click Delete to confirm.

    Result: The HPA is deleted from the current cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html index fb298d00db1..7d108e0ff35 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/horizontal-pod-autoscaler/test-hpas-with-kubectl.html @@ -5,14 +5,14 @@ Testing HPAs with kubectl | Rancher Manager - +
    Version: v2.5

    Testing HPAs with kubectl

    This document describes how to check the status of your HPAs after scaling them up or down with your load testing tool. For information on how to check the status from the Rancher UI (at least version 2.3.x), refer to Managing HPAs with the Rancher UI.

    For HPA to work correctly, service deployments should have resources request definitions for containers. Follow this hello-world example to test if HPA is working correctly.

    1. Configure kubectl to connect to your Kubernetes cluster.

    2. Copy the hello-world deployment manifest below.

      Hello World Manifest
      apiVersion: apps/v1beta2
      kind: Deployment
      metadata:
        labels:
          app: hello-world
        name: hello-world
        namespace: default
      spec:
        replicas: 1
        selector:
          matchLabels:
            app: hello-world
        strategy:
          rollingUpdate:
            maxSurge: 1
            maxUnavailable: 0
          type: RollingUpdate
        template:
          metadata:
            labels:
              app: hello-world
          spec:
            containers:
            - image: rancher/hello-world
              imagePullPolicy: Always
              name: hello-world
              resources:
                requests:
                  cpu: 500m
                  memory: 64Mi
              ports:
              - containerPort: 80
                protocol: TCP
            restartPolicy: Always
      ---
      apiVersion: v1
      kind: Service
      metadata:
        name: hello-world
        namespace: default
      spec:
        ports:
        - port: 80
          protocol: TCP
          targetPort: 80
        selector:
          app: hello-world

    3. Deploy it to your cluster.

      # kubectl create -f <HELLO_WORLD_MANIFEST>

    4. Copy one of the HPAs below based on the metric type you're using:

      Hello World HPA: Resource Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 1000Mi
      Hello World HPA: Custom Metrics
      apiVersion: autoscaling/v2beta1
      kind: HorizontalPodAutoscaler
      metadata:
        name: hello-world
        namespace: default
      spec:
        scaleTargetRef:
          apiVersion: extensions/v1beta1
          kind: Deployment
          name: hello-world
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            targetAverageUtilization: 50
        - type: Resource
          resource:
            name: memory
            targetAverageValue: 100Mi
        - type: Pods
          pods:
            metricName: cpu_system
            targetAverageValue: 20m

    5. View the HPA info and description. Confirm that metric data is shown.

      Resource Metrics
      1. Enter the following commands.
        # kubectl get hpa
        NAME          REFERENCE                TARGETS                     MINPODS   MAXPODS   REPLICAS   AGE
        hello-world   Deployment/hello-world   1253376 / 100Mi, 0% / 50%   1         10        1          6m
        # kubectl describe hpa
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 20:21:16 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             1253376 / 100Mi
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>
      Custom Metrics
      1. Enter the following command.
        # kubectl describe hpa
        You should receive the output that follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Tue, 24 Jul 2018 18:36:28 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             3514368 / 100Mi
          "cpu_system" on pods:                                0 / 20m
          resource cpu on pods  (as a percentage of request):  0% (0) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    ReadyForNewScale    the last scale time was sufficiently old as to warrant a new scale
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:           <none>

    6. Generate a load for the service to test that your pods autoscale as intended. You can use any load-testing tool (Hey, Gatling, etc.), but we're using Hey.

    7. Test that pod autoscaling works as intended.

      To Test Autoscaling Using Resource Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to two pods based on CPU Usage.

      1. View your HPA.
        # kubectl describe hpa
        You should receive output similar to what follows.
        Name:                                                  hello-world
        Namespace:                                             default
        Labels:                                                <none>
        Annotations:                                           <none>
        CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
        Reference:                                             Deployment/hello-world
        Metrics:                                               ( current / target )
          resource memory on pods:                             10928128 / 100Mi
          resource cpu on pods  (as a percentage of request):  56% (280m) / 50%
        Min replicas:                                          1
        Max replicas:                                          10
        Conditions:
          Type            Status  Reason              Message
          ----            ------  ------              -------
          AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
          ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
          ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
        Events:
          Type    Reason             Age   From                       Message
          ----    ------             ----  ----                       -------
          Normal  SuccessfulRescale  13s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm you've scaled to two pods.
           # kubectl get pods
        You should receive output similar to what follows:
           NAME                                                     READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-k8ph2                             1/1       Running   0          1m
           hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Upscale to 3 pods: CPU Usage Up to Target

      Use your load testing tool to upscale to 3 pods based on CPU usage with horizontal-pod-autoscaler-upscale-delay set to 3 minutes.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             9424896 / 100Mi
             resource cpu on pods  (as a percentage of request):  66% (333m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  4m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
         NAME                                                     READY     STATUS    RESTARTS   AGE
         hello-world-54764dfbf8-f46kh                             0/1       Running   0          1m
         hello-world-54764dfbf8-k8ph2                             1/1       Running   0          5m
         hello-world-54764dfbf8-q6l4v                             1/1       Running   0          3h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing to scale down to 1 pod when all metrics are below target for horizontal-pod-autoscaler-downscale-delay (5 minutes by default).

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Mon, 23 Jul 2018 22:22:04 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             10070016 / 100Mi
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  6m    horizontal-pod-autoscaler  New size: 3; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  1s    horizontal-pod-autoscaler  New size: 1; reason: All metrics below target

      To Test Autoscaling Using Custom Metrics:

      Upscale to 2 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale two pods based on CPU usage.

      1. Enter the following command.
          # kubectl describe hpa
        You should receive output similar to what follows.
          Name:                                                  hello-world
          Namespace:                                             default
          Labels:                                                <none>
          Annotations:                                           <none>
          CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
          Reference:                                             Deployment/hello-world
          Metrics:                                               ( current / target )
            resource memory on pods:                             8159232 / 100Mi
            "cpu_system" on pods:                                7m / 20m
            resource cpu on pods  (as a percentage of request):  64% (321m) / 50%
          Min replicas:                                          1
          Max replicas:                                          10
          Conditions:
            Type            Status  Reason              Message
            ----            ------  ------              -------
            AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 2
            ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
            ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
          Events:
            Type    Reason             Age   From                       Message
            ----    ------             ----  ----                       -------
            Normal  SuccessfulRescale  16s   horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm two pods are running.
          # kubectl get pods
        You should receive output similar to what follows.
              NAME                           READY     STATUS    RESTARTS   AGE
              hello-world-54764dfbf8-5pfdr   1/1       Running   0          3s
              hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 3 Pods: CPU Usage Up to Target

      Use your load testing tool to scale up to three pods when the cpu_system usage limit is up to target.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows:
           Name:                                                  hello-world
           Namespace:                                             default
           Labels:                                                <none>
           Annotations:                                           <none>
           CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
           Reference:                                             Deployment/hello-world
           Metrics:                                               ( current / target )
             resource memory on pods:                             8374272 / 100Mi
             "cpu_system" on pods:                                27m / 20m
             resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
           Min replicas:                                          1
           Max replicas:                                          10
           Conditions:
             Type            Status  Reason              Message
             ----            ------  ------              -------
             AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
             ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
             ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
           Events:
             Type    Reason             Age   From                       Message
             ----    ------             ----  ----                       -------
             Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
             Normal  SuccessfulRescale  3s    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
      2. Enter the following command to confirm three pods are running.
        # kubectl get pods
        You should receive output similar to what follows:
           # kubectl get pods
           NAME                           READY     STATUS    RESTARTS   AGE
           hello-world-54764dfbf8-5pfdr   1/1       Running   0          3m
           hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
           hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Upscale to 4 Pods: CPU Usage Up to Target

      Use your load testing tool to upscale to four pods based on CPU usage. horizontal-pod-autoscaler-upscale-delay is set to three minutes by default.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive output similar to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8374272 / 100Mi
              "cpu_system" on pods:                                27m / 20m
              resource cpu on pods  (as a percentage of request):  71% (357m) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 3
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from cpu resource utilization (percentage of request)
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  3m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  4s    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
      2. Enter the following command to confirm four pods are running.
        # kubectl get pods
        You should receive output similar to what follows.
          NAME                           READY     STATUS    RESTARTS   AGE
          hello-world-54764dfbf8-2p9xb   1/1       Running   0          5m
          hello-world-54764dfbf8-5pfdr   1/1       Running   0          2m
          hello-world-54764dfbf8-m2hrl   1/1       Running   0          1s
          hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
      Downscale to 1 Pod: All Metrics Below Target

      Use your load testing tool to scale down to one pod when all metrics below target for horizontal-pod-autoscaler-downscale-delay.

      1. Enter the following command.
        # kubectl describe hpa
        You should receive similar output to what follows.
            Name:                                                  hello-world
            Namespace:                                             default
            Labels:                                                <none>
            Annotations:                                           <none>
            CreationTimestamp:                                     Tue, 24 Jul 2018 18:01:11 +0200
            Reference:                                             Deployment/hello-world
            Metrics:                                               ( current / target )
              resource memory on pods:                             8101888 / 100Mi
              "cpu_system" on pods:                                8m / 20m
              resource cpu on pods  (as a percentage of request):  0% (0) / 50%
            Min replicas:                                          1
            Max replicas:                                          10
            Conditions:
              Type            Status  Reason              Message
              ----            ------  ------              -------
              AbleToScale     True    SucceededRescale    the HPA controller was able to update the target scale to 1
              ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count from memory resource
              ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range
            Events:
              Type    Reason             Age   From                       Message
              ----    ------             ----  ----                       -------
              Normal  SuccessfulRescale  10m    horizontal-pod-autoscaler  New size: 2; reason: cpu resource utilization (percentage of request) above target
              Normal  SuccessfulRescale  8m    horizontal-pod-autoscaler  New size: 3; reason: pods metric cpu_system above target
              Normal  SuccessfulRescale  5m    horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization (percentage of request) above target
              Normal   SuccessfulRescale             13s               horizontal-pod-autoscaler  New size: 1; reason: All metrics below target
      2. Enter the following command to confirm a single pods is running.
            # kubectl get pods
        You should receive output similar to what follows.
            NAME                           READY     STATUS    RESTARTS   AGE
            hello-world-54764dfbf8-q6l82   1/1       Running   0          6h
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html index 72cdc0f149e..0695472ad96 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/kubernetes-and-docker-registries.html @@ -5,13 +5,13 @@ Kubernetes Registry and Docker Registry | Rancher Manager - +
    Version: v2.5

    Kubernetes Registry and Docker Registry

    Registries are Kubernetes secrets containing credentials used to authenticate with private Docker registries.

    The word "registry" can mean two things, depending on whether it is used to refer to a Docker or Kubernetes registry:

    • A Docker registry contains Docker images that you can pull in order to use them in your deployment. The registry is a stateless, scalable server side application that stores and lets you distribute Docker images.
    • The Kubernetes registry is an image pull secret that your deployment uses to authenticate with a Docker registry.

    Deployments use the Kubernetes registry secret to authenticate with a private Docker registry and then pull a Docker image hosted on it.

    Currently, deployments pull the private registry credentials automatically only if the workload is created in the Rancher UI and not when it is created via kubectl.

    Creating a Registry

    Prerequisites: You must have a private registry available to use.

    1. From the Global view, select the project containing the namespace(s) where you want to add a registry.

    2. From the main menu, click Resources > Secrets > Registry Credentials.

    3. Click Add Registry.

    4. Enter a Name for the registry.

      Note: Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your registry must have a unique name among all secrets within your workspace.

    5. Select a Scope for the registry. You can either make the registry available for the entire project or a single namespace.

    6. Select the website that hosts your private registry. Then enter credentials that authenticate with the registry. For example, if you use DockerHub, provide your DockerHub username and password.

    7. Click Save.

    Result:

    • Your secret is added to the project or namespace, depending on the scope you chose.
    • You can view the secret in the Rancher UI from the Resources > Registries view.
    • Any workload that you create in the Rancher UI will have the credentials to access the registry if the workload is within the registry's scope.

    Using a Private Registry

    You can deploy a workload with an image from a private registry through the Rancher UI, or with kubectl.

    Using the Private Registry with the Rancher UI​

    To deploy a workload with an image from your private registry,

    1. Go to the project view,
    2. Click Resources > Workloads.
    3. Click Deploy.
    4. Enter a unique name for the workload and choose a namespace.
    5. In the Docker Image field, enter the URL of the path to the Docker image in your private registry. For example, if your private registry is on Quay.io, you could use quay.io/<Quay profile name>/<Image name>.
    6. Click Launch.

    Result: Your deployment should launch, authenticate using the private registry credentials you added in the Rancher UI, and pull the Docker image that you specified.

    Using the Private Registry with kubectl​

    When you create the workload using kubectl, you need to configure the pod so that its YAML has the path to the image in the private registry. You also have to create and reference the registry secret because the pod only automatically gets access to the private registry credentials if it is created in the Rancher UI.

    The secret has to be created in the same namespace where the workload gets deployed.

    Below is an example pod.yml for a workload that uses an image from a private registry. In this example, the pod uses an image from Quay.io, and the .yml specifies the path to the image. The pod authenticates with the registry using credentials stored in a Kubernetes secret called testquay, which is specified in spec.imagePullSecrets in the name field:

    apiVersion: v1
    kind: Pod
    metadata:
      name: private-reg
    spec:
      containers:
      - name: private-reg-container
        image: quay.io/<Quay profile name>/<image name>
      imagePullSecrets:
      - name: testquay

    In this example, the secret named testquay is in the default namespace.

    You can use kubectl to create the secret with the private registry credentials. This command creates the secret named testquay:

    kubectl create secret docker-registry testquay \
        --docker-server=quay.io \
        --docker-username=<Profile name> \
        --docker-password=<password>

    To see how the secret is stored in Kubernetes, you can use this command:

    kubectl get secret testquay --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode

    The result looks like this:

    {"auths":{"quay.io":{"username":"<Profile name>","password":"<password>","auth":"c291bXlhbGo6dGVzdGFiYzEyMw=="}}}

    After the workload is deployed, you can check if the image was pulled successfully:

    kubectl get events

    The result should look like this:

    14s         Normal    Scheduled          Pod    Successfully assigned default/private-reg2 to minikube
    11s         Normal    Pulling            Pod    pulling image "quay.io/<Profile name>/<image name>"
    10s         Normal    Pulled             Pod    Successfully pulled image "quay.io/<Profile name>/<image name>"

    For more information, refer to the Kubernetes documentation on creating a pod that uses your secret.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html index eb165f67cf4..7f31190f469 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/add-ingresses.html @@ -5,13 +5,13 @@ Adding Ingresses to Your Project | Rancher Manager - +
    Version: v2.5

    Adding Ingresses to Your Project

    Ingress can be added for workloads to provide load balancing, SSL termination and host/path based routing. When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    1. From the Global view, open the project that you want to add ingress to.
    2. Click Resources in the main navigation bar. Click the Load Balancing tab. Then click Add Ingress.
    3. Enter a Name for the ingress.
    4. Select an existing Namespace from the drop-down list. Alternatively, you can create a new namespace on the fly by clicking Add to a new namespace.
    5. Create ingress forwarding Rules. For help configuring the rules, refer to this section. If any of your ingress rules handle requests for encrypted ports, add a certificate to encrypt/decrypt communications.
    6. Optional: click Add Rule to create additional ingress rules. For example, after you create ingress rules to direct requests for your hostname, you'll likely want to create a default backend to handle 404s.

    Result: Your ingress is added to the project. The ingress begins enforcing your ingress rules.

    Ingress Rule Configuration

    Automatically generate a sslip.io hostname​

    If you choose this option, ingress routes requests to hostname to a DNS name that's automatically generated. Rancher uses sslip.io to automatically generates the DNS name. This option is best used for testing, not production environments.

    Note: To use this option, you must be able to resolve to sslip.io addresses.

    1. Add a Target Backend. By default, a workload is added to the ingress, but you can add more targets by clicking either Service or Workload.
    2. Optional: If you want specify a workload or service when a request is sent to a particular hostname path, add a Path for the target. For example, if you want requests for www.mysite.com/contact-us to be sent to a different service than www.mysite.com, enter /contact-us in the Path field. Typically, the first rule that you create does not include a path.
    3. Select a workload or service from the Target drop-down list for each target you've added.
    4. Enter the Port number that each target operates on.

    Specify a hostname to use​

    If you use this option, ingress routes requests for a hostname to the service or workload that you specify.

    1. Enter the hostname that your ingress will handle request forwarding for. For example, www.mysite.com.
    2. Add a Target Backend. By default, a workload is added to the ingress, but you can add more targets by clicking either Service or Workload.
    3. Optional: If you want specify a workload or service when a request is sent to a particular hostname path, add a Path for the target. For example, if you want requests for www.mysite.com/contact-us to be sent to a different service than www.mysite.com, enter /contact-us in the Path field. Typically, the first rule that you create does not include a path.
    4. Select a workload or service from the Target drop-down list for each target you've added.
    5. Enter the Port number that each target operates on.

    Use as the default backend​

    Use this option to set an ingress rule for handling requests that don't match any other ingress rules. For example, use this option to route requests that can't be found to a 404 page.

    Note: If you deployed Rancher using RKE, a default backend for 404s and 202s is already configured.

    1. Add a Target Backend. Click either Service or Workload to add the target.
    2. Select a service or workload from the Target drop-down list.

    Certificates​

    Note: You must have an SSL certificate that the ingress can use to encrypt/decrypt communications. For more information see Adding SSL Certificates.

    1. Click Add Certificate.
    2. Select a Certificate from the drop-down list.
    3. Enter the Host using encrypted communication.
    4. To add additional hosts that use the certificate, click Add Hosts.

    Labels and Annotations​

    Add Labels and/or Annotations to provide metadata for your ingress.

    For a list of annotations available for use, see the Nginx Ingress Controller Documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html index 40303dca6fe..a55638fcaf2 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing.html @@ -5,13 +5,13 @@ Layer 4 and Layer 7 Load Balancing | Rancher Manager - +
    Version: v2.5

    Layer 4 and Layer 7 Load Balancing

    Kubernetes supports load balancing in two ways: Layer-4 Load Balancing and Layer-7 Load Balancing.

    Layer-4 Load Balancer​

    Layer-4 load balancer (or the external load balancer) forwards traffic to Nodeports. Layer-4 load balancer allows you to forward both HTTP and TCP traffic.

    Often, the Layer-4 load balancer is supported by the underlying cloud provider, so when you deploy RKE clusters on bare-metal servers and vSphere clusters, Layer-4 load balancer is not supported. However, a single globally managed config-map can be used to expose services on NGINX or third-party ingress.

    Note: It is possible to deploy a cluster with a non-cloud load balancer, such as MetalLB. However, that use case is more advanced than the Layer-4 load balancer supported by a cloud provider, and it is not configurable in Rancher or RKE.

    Support for Layer-4 Load Balancing​

    Support for layer-4 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-4 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GCE cloud provider
    Azure AKSSupported by Azure cloud provider
    RKE on EC2Supported by AWS cloud provider
    RKE on DigitalOceanLimited NGINX or third-party Ingress*
    RKE on vSphereLimited NGINX or third party-Ingress*
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Limited NGINX or third-party Ingress*
    Third-party MetalLBLimited NGINX or third-party Ingress*

    * Services can be exposed through a single globally managed config-map.

    Layer-7 Load Balancer​

    Layer-7 load balancer (or the ingress controller) supports host and path-based load balancing and SSL termination. Layer-7 load balancer only forwards HTTP and HTTPS traffic and therefore they listen on ports 80 and 443 only. Cloud providers such as Amazon and Google support layer-7 load balancer. In addition, RKE clusters deploys the Nginx Ingress Controller.

    Support for Layer-7 Load Balancing​

    Support for layer-7 load balancer varies based on the underlying cloud provider.

    Cluster DeploymentLayer-7 Load Balancer Support
    Amazon EKSSupported by AWS cloud provider
    Google GKESupported by GKE cloud provider
    Azure AKSNot Supported
    RKE on EC2Nginx Ingress Controller
    RKE on DigitalOceanNginx Ingress Controller
    RKE on vSphereNginx Ingress Controller
    RKE on Custom Hosts
    (e.g. bare-metal servers)    		Nginx Ingress Controller

    Host Names in Layer-7 Load Balancer​

    Some cloud-managed layer-7 load balancers (such as the ALB ingress controller on AWS) expose DNS addresses for ingress rules. You need to map (via CNAME) your domain name to the DNS address generated by the layer-7 load balancer.

    Other layer-7 load balancers, such as the Google Load Balancer or Nginx Ingress Controller, directly expose one or more IP addresses. Google Load Balancer provides a single routable IP address. Nginx Ingress Controller exposes the external IP of all nodes that run the Nginx Ingress Controller. You can do either of the following:

    1. Configure your own DNS to map (via A records) your domain name to the IP addresses exposes by the Layer-7 load balancer.
    2. Ask Rancher to generate an sslip.io host name for your ingress rule. Rancher will take one of your exposed IPs, say a.b.c.d, and generate a host name <ingressname>.<namespace>.a.b.c.d.sslip.io.

    The benefit of using sslip.io is that you obtain a working entrypoint URL immediately after you create the ingress rule. Setting up your own domain name, on the other hand, requires you to configure DNS servers and wait for DNS to propagate.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html index 6da143317c1..4a22be88272 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.html @@ -5,13 +5,13 @@ Secrets | Rancher Manager - +
    Version: v2.5

    Secrets

    Secrets store sensitive data like passwords, tokens, or keys. They may contain one or more key value pairs.

    This page is about secrets in general. For details on setting up a private registry, refer to the section on registries.

    When configuring a workload, you'll be able to choose which secrets to include. Like config maps, secrets can be referenced by workloads as either an environment variable or a volume mount.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    Creating Secrets

    When creating a secret, you can make it available for any deployment within a project, or you can limit it to a single namespace.

    1. From the Global view, select the project containing the namespace(s) where you want to add a secret.

    2. From the main menu, select Resources > Secrets. Click Add Secret.

    3. Enter a Name for the secret.

      Note: Kubernetes classifies secrets, certificates, and registries all as secrets, and no two secrets in a project or namespace can have duplicate names. Therefore, to prevent conflicts, your secret must have a unique name among all secrets within your workspace.

    4. Select a Scope for the secret. You can either make the registry available for the entire project or a single namespace.

    5. From Secret Values, click Add Secret Value to add a key value pair. Add as many values as you need.

      Tip: You can add multiple key value pairs to the secret by copying and pasting.

    6. Click Save.

    Result: Your secret is added to the project or namespace, depending on the scope you chose. You can view the secret in the Rancher UI from the Resources > Secrets view.

    Mounted secrets will be updated automatically unless they are mounted as subpath volumes. For details on how updated secrets are propagated, refer to the Kubernetes documentation.

    What's Next?

    Now that you have a secret added to the project or namespace, you can add it to a workload that you deploy.

    For more information on adding secret to a workload, see Deploying Workloads.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html index cc4ef3eed8d..7a650cdaadc 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/add-a-sidecar.html @@ -5,13 +5,13 @@ Adding a Sidecar | Rancher Manager - +
    Version: v2.5

    Adding a Sidecar

    A sidecar is a container that extends or enhances the main container in a pod. The main container and the sidecar share a pod, and therefore share the same network space and storage. You can add sidecars to existing workloads by using the Add a Sidecar option.

    1. From the Global view, open the project running the workload you want to add a sidecar to.

    2. Click Resources > Workloads.

    3. Find the workload that you want to extend. Select ⋮ icon (...) > Add a Sidecar.

    4. Enter a Name for the sidecar.

    5. Select a Sidecar Type. This option determines if the sidecar container is deployed before or after the main container is deployed.

      • Standard Container:

        The sidecar container is deployed after the main container.

      • Init Container:

        The sidecar container is deployed before the main container.

    6. From the Docker Image field, enter the name of the Docker image that you want to deploy in support of the main container. During deployment, Rancher pulls this image from Docker Hub. Enter the name exactly as it appears on Docker Hub.

    7. Set the remaining options. You can read about them in Deploying Workloads.

    8. Click Launch.

    Result: The sidecar is deployed according to your parameters. Following its deployment, you can view the sidecar by selecting ⋮ icon (...) > Edit for the main deployment.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html index e179d3f2877..880fb5715ec 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/deploy-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Version: v2.5

    Deploying Workloads

    Deploy a workload to run an application in one or more containers.

    1. From the Global view, open the project that you want to deploy a workload to.

      1. Click Resources > Workloads. From the Workloads view, click Deploy.

    3. Enter a Name for the workload.

    4. Select a workload type. The workload defaults to a scalable deployment, but you can change the workload type by clicking More options.

    5. From the Docker Image field, enter the name of the Docker image that you want to deploy to the project, optionally prefacing it with the registry host (e.g. quay.io, registry.gitlab.com, etc.). During deployment, Rancher pulls this image from the specified public or private registry. If no registry host is provided, Rancher will pull the image from Docker Hub. Enter the name exactly as it appears in the registry server, including any required path, and optionally including the desired tag (e.g. registry.gitlab.com/user/path/image:tag). If no tag is provided, the latest tag will be automatically used.

    6. Either select an existing namespace, or click Add to a new namespace and enter a new namespace.

    7. Click Add Port to enter a port mapping, which enables access to the application inside and outside of the cluster . For more information, see Services.

    8. Configure the remaining options:

      • Environment Variables

        Use this section to either specify environment variables for your workload to consume on the fly, or to pull them from another source, such as a secret or ConfigMap.

      • Node Scheduling

      • Health Check

      • Volumes

        Use this section to add storage for your workload. You can manually specify the volume that you want to add, use a persistent volume claim to dynamically create a volume for the workload, or read data for a volume to use from a file such as a ConfigMap.

        When you are deploying a Stateful Set, you should use a Volume Claim Template when using Persistent Volumes. This will ensure that Persistent Volumes are created dynamically when you scale your Stateful Set.

      • Scaling/Upgrade Policy

        Amazon Note for Volumes:

        To mount an Amazon EBS volume:

    1. Click Show Advanced Options and configure:

      • Command
      • Networking
      • Labels & Annotations
      • Security and Host Config

    2. Click Launch.

    Result: The workload is deployed to the chosen namespace. You can view the workload's status from the project's Workloads view.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html index 6aead18780f..a7fe8ab2799 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/roll-back-workloads.html @@ -5,13 +5,13 @@ Rolling Back Workloads | Rancher Manager - +
    Version: v2.5

    Rolling Back Workloads

    Sometimes there is a need to rollback to the previous version of the application, either for debugging purposes or because an upgrade did not go as planned.

    1. From the Global view, open the project running the workload you want to rollback.

    2. Find the workload that you want to rollback and select Vertical ⋮ (... ) > Rollback.

    3. Choose the revision that you want to roll back to. Click Rollback.

    Result: Your workload reverts to the previous version that you chose. Wait a few minutes for the action to complete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html index 748fdbdd449..e134103ef1f 100644 --- a/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html +++ b/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/workloads-and-pods/upgrade-workloads.html @@ -5,13 +5,13 @@ Upgrading Workloads | Rancher Manager - +
    Version: v2.5

    Upgrading Workloads

    When a new version of an application image is released on Docker Hub, you can upgrade any workloads running a previous version of the application to the new one.

    1. From the Global view, open the project running the workload you want to upgrade.

    2. Find the workload that you want to upgrade and select Vertical ⋮ (... ) > Edit.

    3. Update the Docker Image to the updated version of the application image on Docker Hub.

    4. Update any other options that you want to change.

    5. Review and edit the workload's Scaling/Upgrade policy.

      These options control how the upgrade rolls out to containers that are currently running. For example, for scalable deployments, you can choose whether you want to stop old pods before deploying new ones, or vice versa, as well as the upgrade batch size.

    6. Click Upgrade.

    Result: The workload begins upgrading its containers, per your specifications. Note that scaling up the deployment or updating the upgrade/scaling policy won't result in the pods recreation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/about-authentication.html b/v2.5/pages-for-subheaders/about-authentication.html index c6ce736bb36..4d6a6281528 100644 --- a/v2.5/pages-for-subheaders/about-authentication.html +++ b/v2.5/pages-for-subheaders/about-authentication.html @@ -5,13 +5,13 @@ Authentication | Rancher Manager - +
    Version: v2.5

    Authentication

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows your users to use one set of credentials to authenticate with any of your Kubernetes clusters.

    This centralized user authentication is accomplished using the Rancher authentication proxy, which is installed along with the rest of Rancher. This proxy authenticates your users and forwards their requests to your Kubernetes clusters using a service account.

    External vs. Local Authentication​

    The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted.

    Auth Service
    Microsoft Active Directory
    GitHub
    Microsoft Azure AD
    FreeIPA
    OpenLDAP
    Microsoft AD FS
    PingIdentity
    Keycloak
    Okta
    Google OAuth
    Shibboleth

    However, Rancher also provides [local authentication](/v2.5/how-to-guides/advanced-user-guides/authentication-permissions-and-global-configuration/about-authentication/authentication-config/create-local-users).

    In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if your external authentication provider is unavailable or undergoing maintenance.

    Users and Groups​

    Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see Role Based Access Control.

    Note: Local authentication does not support creating or managing groups.

    For more information, see Users and Groups

    Scope of Rancher Authorization​

    After you configure Rancher to allow sign on using an external authentication service, you should configure who should be allowed to log in and use Rancher. The following options are available:

    Access LevelDescription
    Allow any valid UsersAny user in the authorization service can access Rancher. We generally discourage use of this setting!
    Allow members of Clusters, Projects, plus Authorized Users and OrganizationsAny user in the authorization service and any group added as a Cluster Member or Project Member can log in to Rancher. Additionally, any user in the authentication service or group you add to the Authorized Users and Organizations list may log in to Rancher.
    Restrict access to only Authorized Users and OrganizationsOnly users in the authentication service or groups added to the Authorized Users and Organizations can log in to Rancher.

    To set the Rancher access level for users in the authorization service, follow these steps:

    1. From the Global view, click Security > Authentication.

    2. Use the Site Access options to configure the scope of user authorization. The table above explains the access level for each option.

    3. Optional: If you choose an option other than Allow any valid Users, you can add users to the list of authorized users and organizations by searching for them in the text field that appears.

    4. Click Save.

    Result: The Rancher access configuration settings are applied.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    External Authentication Configuration and Principal Users​

    Configuration of external authentication requires:

    • A local user assigned the administrator role, called hereafter the local principal.
    • An external user that can authenticate with your external authentication service, called hereafter the external principal.

    Configuration of external authentication affects how principal users are managed within Rancher. Follow the list below to better understand these effects.

    1. Sign into Rancher as the local principal and complete configuration of external authentication.

      Sign In

    2. Rancher associates the external principal with the local principal. These two users share the local principal's user ID.

      Principal ID Sharing

    3. After you complete configuration, Rancher automatically signs out the local principal.

      Sign Out Local Principal

    4. Then, Rancher automatically signs you back in as the external principal.

      Sign In External Principal

    5. Because the external principal and the local principal share an ID, no unique object for the external principal displays on the Users page.

      Sign In External Principal

    6. The external principal and the local principal share the same access rights.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/about-provisioning-drivers.html b/v2.5/pages-for-subheaders/about-provisioning-drivers.html index 5a46b254ad5..a8e69e40c0f 100644 --- a/v2.5/pages-for-subheaders/about-provisioning-drivers.html +++ b/v2.5/pages-for-subheaders/about-provisioning-drivers.html @@ -5,13 +5,13 @@ Provisioning Drivers | Rancher Manager - +
    Version: v2.5

    Provisioning Drivers

    Drivers in Rancher allow you to manage which providers can be used to deploy hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    Rancher Drivers​

    With Rancher drivers, you can enable/disable existing built-in drivers that are packaged in Rancher. Alternatively, you can add your own driver if Rancher has not yet implemented it.

    There are two types of drivers within Rancher:

    Cluster Drivers​

    Cluster drivers are used to provision hosted Kubernetes clusters, such as GKE, EKS, AKS, etc.. The availability of which cluster driver to display when creating a cluster is defined based on the cluster driver's status. Only active cluster drivers will be displayed as an option for creating clusters for hosted Kubernetes clusters. By default, Rancher is packaged with several existing cluster drivers, but you can also create custom cluster drivers to add to Rancher.

    By default, Rancher has activated several hosted Kubernetes cloud providers including:

    There are several other hosted Kubernetes cloud providers that are disabled by default, but are packaged in Rancher:

    Node Drivers​

    Node drivers are used to provision hosts, which Rancher uses to launch and manage Kubernetes clusters. A node driver is the same as a Docker Machine driver. The availability of which node driver to display when creating node templates is defined based on the node driver's status. Only active node drivers will be displayed as an option for creating node templates. By default, Rancher is packaged with many existing Docker Machine drivers, but you can also create custom node drivers to add to Rancher.

    If there are specific node drivers that you don't want to show to your users, you would need to de-activate these node drivers.

    Rancher supports several major cloud providers, but by default, these node drivers are active and available for deployment:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/about-rke1-templates.html b/v2.5/pages-for-subheaders/about-rke1-templates.html index 82910080010..782e69ac8bb 100644 --- a/v2.5/pages-for-subheaders/about-rke1-templates.html +++ b/v2.5/pages-for-subheaders/about-rke1-templates.html @@ -5,13 +5,13 @@ RKE Templates | Rancher Manager - +
    Version: v2.5

    RKE Templates

    RKE templates are designed to allow DevOps and security teams to standardize and simplify the creation of Kubernetes clusters.

    RKE is the Rancher Kubernetes Engine, which is the tool that Rancher uses to provision Kubernetes clusters.

    With Kubernetes increasing in popularity, there is a trend toward managing a larger number of smaller clusters. When you want to create many clusters, it’s more important to manage them consistently. Multi-cluster management comes with challenges to enforcing security and add-on configurations that need to be standardized before turning clusters over to end users.

    RKE templates help standardize these configurations. Regardless of whether clusters are created with the Rancher UI, the Rancher API, or an automated process, Rancher will guarantee that every cluster it provisions from an RKE template is uniform and consistent in the way it is produced.

    Admins control which cluster options can be changed by end users. RKE templates can also be shared with specific users and groups, so that admins can create different RKE templates for different sets of users.

    If a cluster was created with an RKE template, you can't change it to a different RKE template. You can only update the cluster to a new revision of the same template.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated. The new template can also be used to launch new clusters.

    The core features of RKE templates allow DevOps and security teams to:

    • Standardize cluster configuration and ensure that Rancher-provisioned clusters are created following best practices
    • Prevent less technical users from making uninformed choices when provisioning clusters
    • Share different templates with different sets of users and groups
    • Delegate ownership of templates to users who are trusted to make changes to them
    • Control which users can create templates
    • Require users to create clusters from a template

    Configurable Settings​

    RKE templates can be created in the Rancher UI or defined in YAML format. They can define all the same parameters that can be specified when you use Rancher to provision custom nodes or nodes from an infrastructure provider:

    • Cloud provider options
    • Pod security options
    • Network providers
    • Ingress controllers
    • Network security configuration
    • Network plugins
    • Private registry URL and credentials
    • Add-ons
    • Kubernetes options, including configurations for Kubernetes components such as kube-api, kube-controller, kubelet, and services

    The add-on section of an RKE template is especially powerful because it allows a wide range of customization options.

    Scope of RKE Templates​

    RKE templates are supported for Rancher-provisioned clusters. The templates can be used to provision custom clusters or clusters that are launched by an infrastructure provider.

    RKE templates are for defining Kubernetes and Rancher settings. Node templates are responsible for configuring nodes. For tips on how to use RKE templates in conjunction with hardware, refer to RKE Templates and Hardware.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    The settings of an existing cluster can be saved as an RKE template. This creates a new template and binds the cluster settings to the template, so that the cluster can only be upgraded if the template is updated, and the cluster is upgraded to use a newer version of the template. The new template can also be used to create new clusters.

    Example Scenarios​

    When an organization has both basic and advanced Rancher users, administrators might want to give the advanced users more options for cluster creation, while restricting the options for basic users.

    These example scenarios describe how an organization could use templates to standardize cluster creation.

    Some of the example scenarios include the following:

    Template Management​

    When you create an RKE template, it is available in the Rancher UI from the Global view under Tools > RKE Templates. When you create a template, you become the template owner, which gives you permission to revise and share the template. You can share the RKE templates with specific users or groups, and you can also make it public.

    Administrators can turn on template enforcement to require users to always use RKE templates when creating a cluster. This allows administrators to guarantee that Rancher always provisions clusters with specific settings.

    RKE template updates are handled through a revision system. If you want to change or update a template, you create a new revision of the template. Then a cluster that was created with the older version of the template can be upgraded to the new template revision.

    In an RKE template, settings can be restricted to what the template owner chooses, or they can be open for the end user to select the value. The difference is indicated by the Allow User Override toggle over each setting in the Rancher UI when the template is created.

    For the settings that cannot be overridden, the end user will not be able to directly edit them. In order for a user to get different options of these settings, an RKE template owner would need to create a new revision of the RKE template, which would allow the user to upgrade and change that option.

    The documents in this section explain the details of RKE template management:

    An example YAML configuration file for a template is provided for reference.

    Applying Templates​

    You can create a cluster from a template that you created, or from a template that has been shared with you.

    If the RKE template owner creates a new revision of the template, you can upgrade your cluster to that revision.

    RKE templates can be created from scratch to pre-define cluster configuration. They can be applied to launch new clusters, or templates can also be exported from existing running clusters.

    You can save the configuration of an existing cluster as an RKE template. Then the cluster's settings can only be changed if the template is updated.

    Standardizing Hardware​

    RKE templates are designed to standardize Kubernetes and Rancher settings. If you want to standardize your infrastructure as well, you use RKE templates in conjunction with other tools.

    YAML Customization​

    If you define an RKE template as a YAML file, you can modify this example RKE template YAML. The YAML in the RKE template uses the same customization that Rancher uses when creating an RKE cluster, but since the YAML is located within the context of a Rancher provisioned cluster, you will need to nest the RKE template customization under the rancher_kubernetes_engine_config directive in the YAML.

    The RKE documentation also has annotated cluster.yml files that you can use for reference.

    For guidance on available options, refer to the RKE documentation on cluster configuration.

    Add-ons​

    The add-on section of the RKE template configuration file works the same way as the add-on section of a cluster configuration file.

    The user-defined add-ons directive allows you to either call out and pull down Kubernetes manifests or put them inline directly. If you include these manifests as part of your RKE template, Rancher will provision those in the cluster.

    Some things you could do with add-ons include:

    • Install applications on the Kubernetes cluster after it starts
    • Install plugins on nodes that are deployed with a Kubernetes daemonset
    • Automatically set up namespaces, service accounts, or role binding

    The RKE template configuration must be nested within the rancher_kubernetes_engine_config directive. To set add-ons, when creating the template, you will click Edit as YAML. Then use the addons directive to add a manifest, or the addons_include directive to set which YAML files are used for the add-ons. For more information on custom add-ons, refer to the user-defined add-ons documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/about-the-api.html b/v2.5/pages-for-subheaders/about-the-api.html index 77d8d46f17f..91ce7898006 100644 --- a/v2.5/pages-for-subheaders/about-the-api.html +++ b/v2.5/pages-for-subheaders/about-the-api.html @@ -5,13 +5,13 @@ API | Rancher Manager - +
    Version: v2.5

    API

    How to use the API​

    The API has its own user interface accessible from a web browser. This is an easy way to see resources, perform actions, and see the equivalent cURL or HTTP request & response. To access it, click on your user avatar in the upper right corner. Under API & Keys, you can find the URL endpoint as well as create API keys.

    Authentication​

    API requests must include authentication information. Authentication is done with HTTP basic authentication using API Keys. API keys can create new clusters and have access to multiple clusters via /v3/clusters/. Cluster and project roles apply to these keys and restrict what clusters and projects the account can see and what actions they can take.

    By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. For details on how to invalidate them, refer to the API tokens page.

    Making requests​

    The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, see here.

    • Every type has a Schema which describes:
      • The URL to get to the collection of this type of resources
      • Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
      • Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
      • Every field that filtering is allowed on
      • What HTTP verb methods are available for the collection itself, or for individual resources in the collection.

    • So the theory is that you can load just the list of schemas and know everything about the API. This is in fact how the UI for the API works, it contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a X-Api-Schemas header. From there you can follow the collection link on each schema to know where to list resources, and other links inside of the returned resources to get any other information.

    • In practice, you will probably just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (/v3/<type>) or get a specific resource (/v3/<type>/<id>). Anything deeper than that is subject to change in future releases.

    • Resources have relationships between each other called links. Each resource includes a map of links with the name of the link and the URL to retrieve that information. Again you should GET the resource and then follow the URL in the links map, not construct these strings yourself.

    • Most resources have actions, which do something or change the state of the resource. To use these, send a HTTP POST to the URL in the actions map for the action you want. Some actions require input or produce output, see the individual documentation for each type or the schemas for specific information.

    • To edit a resource, send a HTTP PUT to the links.update link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.

    • To delete a resource, send a HTTP DELETE to the links.remove link on the resource. If the link is missing then you don't have permission to update the resource.

    • To create a new resource, HTTP POST to the collection URL in the schema (which is /v3/<type>).

    Filtering​

    Most collections can be filtered on the server-side by common fields using HTTP query parameters. The filters map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just field=value. Modifiers can be added to the field name, e.g. field_gt=42 for "field is greater than 42". See the API spec for full details.

    Sorting​

    Most collections can be sorted on the server-side by common fields using HTTP query parameters. The sortLinks map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.

    Pagination​

    API responses are paginated with a limit of 100 resources per page by default. This can be changed with the limit query parameter, up to a maximum of 1000, e.g. /v3/pods?limit=1000. The pagination map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.

    Capturing Rancher API Calls​

    You can use browser developer tools to capture how the Rancher API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning an RKE cluster:

    1. In the Rancher UI, go to Cluster Management and click Create.
    2. Click one of the cluster types. This example uses Digital Ocean.
    3. Fill out the form with a cluster name and node template, but don't click Create.
    4. You will need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click on the Rancher UI and click Inspect.
    5. In the developer tools, click the Network tab.
    6. On the Network tab, make sure Fetch/XHR is selected.
    7. In the Rancher UI, click Create. In the developer tools, you should see a new network request with the name cluster?_replace=true.
    8. Right-click cluster?_replace=true and click Copy > Copy as cURL.
    9. Paste the result into any text editor. You will be able to see the POST request, including the URL it was sent to, all of the headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: The request should be stored in a safe place because it contains credentials.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/access-clusters.html b/v2.5/pages-for-subheaders/access-clusters.html index ff9abb864ae..8a459430a01 100644 --- a/v2.5/pages-for-subheaders/access-clusters.html +++ b/v2.5/pages-for-subheaders/access-clusters.html @@ -5,13 +5,13 @@ Cluster Access | Rancher Manager - +
    Version: v2.5

    Cluster Access

    This section is about what tools can be used to access clusters managed by Rancher.

    For information on how to give users permission to access a cluster, see the section on adding users to clusters.

    For more information on roles-based access control, see this section.

    For information on how to set up an authentication system, see this section.

    Rancher UI​

    Rancher provides an intuitive user interface for interacting with your clusters. All options available in the UI use the Rancher API. Therefore any action possible in the UI is also possible in the Rancher CLI or Rancher API.

    kubectl​

    You can use the Kubernetes command-line tool, kubectl, to manage your clusters. You have two options for using kubectl:

    • Rancher kubectl shell: Interact with your clusters by launching a kubectl shell available in the Rancher UI. This option requires no configuration actions on your part. For more information, see Accessing Clusters with kubectl Shell.
    • Terminal remote connection: You can also interact with your clusters by installing kubectl on your local desktop and then copying the cluster's kubeconfig file to your local ~/.kube/config directory. For more information, see Accessing Clusters with kubectl and a kubeconfig File.

    Rancher CLI​

    You can control your clusters by downloading Rancher's own command-line interface, Rancher CLI. This CLI tool can interact directly with different clusters and projects or pass them kubectl commands.

    Rancher API​

    Finally, you can interact with your clusters over the Rancher API. Before you use the API, you must obtain an API key. To view the different resource fields and actions for an API object, open the API UI, which can be accessed by clicking on View in API for any Rancher UI object.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/advanced-configuration.html b/v2.5/pages-for-subheaders/advanced-configuration.html index a57f6f27163..9de69db691d 100644 --- a/v2.5/pages-for-subheaders/advanced-configuration.html +++ b/v2.5/pages-for-subheaders/advanced-configuration.html @@ -5,13 +5,13 @@ Advanced Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/advanced-options.html b/v2.5/pages-for-subheaders/advanced-options.html index d2b0cb7370d..4a964891e9e 100644 --- a/v2.5/pages-for-subheaders/advanced-options.html +++ b/v2.5/pages-for-subheaders/advanced-options.html @@ -5,13 +5,13 @@ Advanced | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/advanced-user-guides.html b/v2.5/pages-for-subheaders/advanced-user-guides.html index ae0fa3d406b..bdc8e751e11 100644 --- a/v2.5/pages-for-subheaders/advanced-user-guides.html +++ b/v2.5/pages-for-subheaders/advanced-user-guides.html @@ -5,13 +5,13 @@ Advanced User Guides | Rancher Manager - +
    Version: v2.5

    Advanced User Guides

    Advanced user guides are "problem-oriented" docs in which users learn how to answer questions or solve problems. The major difference between these and the new user guides is that these guides are geared toward more experienced or advanced users who have more technical needs from their documentation. These users already have an understanding of Rancher and its functions. They know what they need to accomplish; they just need additional guidance to complete some more complex task they they have encountered while working.

    It should be noted that neither new user guides nor advanced user guides provide detailed explanations or discussions (these kinds of docs belong elsewhere). How-to guides focus on the action of guiding users through repeatable, effective steps to learn new skills, master some task, or overcome some problem.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/air-gapped-helm-cli-install.html b/v2.5/pages-for-subheaders/air-gapped-helm-cli-install.html index a407171d127..1082963445b 100644 --- a/v2.5/pages-for-subheaders/air-gapped-helm-cli-install.html +++ b/v2.5/pages-for-subheaders/air-gapped-helm-cli-install.html @@ -5,13 +5,13 @@ Air Gapped Helm CLI Install | Rancher Manager - +
    Version: v2.5

    Air Gapped Helm CLI Install

    This section is about using the Helm CLI to install the Rancher server in an air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    The installation steps differ depending on whether Rancher is installed on an RKE Kubernetes cluster, a K3s Kubernetes cluster, or a single Docker container.

    For more information on each installation option, refer to this page.

    Throughout the installation instructions, there will be tabs for each installation option.

    Important: If you install Rancher following the Docker installation guide, there is no upgrade path to transition your Docker Installation to a Kubernetes Installation.

    Installation Outline

    1. Set up infrastructure and private registry
    2. Collect and publish images to your private registry
    3. Set up a Kubernetes cluster (Skip this step for Docker installations)
    4. Install Rancher

    Upgrades

    To upgrade Rancher with Helm CLI in an air gap environment, follow this procedure.

    Next: Prepare your Node(s)​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/amazon-eks-permissions.html b/v2.5/pages-for-subheaders/amazon-eks-permissions.html index 94e6b915dfa..c5204534af3 100644 --- a/v2.5/pages-for-subheaders/amazon-eks-permissions.html +++ b/v2.5/pages-for-subheaders/amazon-eks-permissions.html @@ -5,14 +5,14 @@ Creating an EKS Cluster | Rancher Manager - +
    Version: v2.5

    Creating an EKS Cluster

    Amazon EKS provides a managed control plane for your Kubernetes cluster. Amazon EKS runs the Kubernetes control plane instances across multiple Availability Zones to ensure high availability. Rancher provides an intuitive user interface for managing and deploying the Kubernetes clusters you run in Amazon EKS. With this guide, you will use Rancher to quickly and easily launch an Amazon EKS Kubernetes cluster in your AWS account. For more information on Amazon EKS, see this documentation.

    Prerequisites in Amazon Web Services​

    Note Deploying to Amazon AWS will incur charges. For more information, refer to the EKS pricing page.

    To set up a cluster on EKS, you will need to set up an Amazon VPC (Virtual Private Cloud). You will also need to make sure that the account you will be using to create the EKS cluster has the appropriate permissions. For details, refer to the official guide on Amazon EKS Prerequisites.

    Amazon VPC​

    An Amazon VPC is required to launch the EKS cluster. The VPC enables you to launch AWS resources into a virtual network that you've defined. You can set one up yourself and provide it during cluster creation in Rancher. If you do not provide one during creation, Rancher will create one. For more information, refer to the Tutorial: Creating a VPC with Public and Private Subnets for Your Amazon EKS Cluster.

    IAM Policies​

    Rancher needs access to your AWS account in order to provision and administer your Kubernetes clusters in Amazon EKS. You'll need to create a user for Rancher in your AWS account and define what that user can access.

    1. Create a user with programmatic access by following the steps here.

    2. Next, create an IAM policy that defines what this user has access to in your AWS account. It's important to only grant this user minimal access within your account. The minimum permissions required for an EKS cluster are listed here. Follow the steps here to create an IAM policy and attach it to your user.

    3. Finally, follow the steps here to create an access key and secret key for this user.

    Note: It's important to regularly rotate your access and secret keys. See this documentation for more information.

    For more detailed information on IAM policies for EKS, refer to the official documentation on Amazon EKS IAM Policies, Roles, and Permissions.

    Create the EKS Cluster​

    Use Rancher to set up and configure your Kubernetes cluster.

    1. From the Clusters page, click Add Cluster.

    2. Choose Amazon EKS.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Fill out the rest of the form. For help, refer to the configuration reference.

    6. Click Create.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    EKS Cluster Configuration Reference​

    For the full list of EKS cluster configuration options, see this page.

    Architecture​

    The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two Kubernetes clusters: one created by RKE and another created by EKS.

    Managing Kubernetes Clusters through Rancher's Authentication Proxy

    Architecture

    AWS Service Events​

    To find information on any AWS Service events, please see this page.

    Security and Compliance​

    By default only the IAM user or role that created a cluster has access to it. Attempting to access the cluster with any other user or role without additional configuration will lead to an error. In Rancher, this means using a credential that maps to a user or role that was not used to create the cluster will cause an unauthorized error. For example, an EKSCtl cluster will not register in Rancher unless the credentials used to register the cluster match the role or user used by EKSCtl. Additional users and roles can be authorized to access a cluster by being added to the aws-auth configmap in the kube-system namespace. For a more in-depth explanation and detailed instructions, please see this documentation.

    For more information on security and compliance with your Amazon EKS Kubernetes cluster, please see this documentation.

    Tutorial​

    This tutorial on the AWS Open Source Blog will walk you through how to set up an EKS cluster with Rancher, deploy a publicly accessible app to test the cluster, and deploy a sample project to track real-time geospatial data using a combination of other open-source software such as Grafana and InfluxDB.

    Minimum EKS Permissions​

    See this page for the minimum set of permissions necessary to use all functionality of the EKS driver in Rancher.

    Syncing​

    The EKS provisioner can synchronize the state of an EKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

    For information on configuring the refresh interval, refer to this section.

    Troubleshooting​

    If your changes were overwritten, it could be due to the way the cluster data is synced with EKS. Changes shouldn't be made to the cluster from another source, such as in the EKS console, and in Rancher within a five-minute span. For information on how this works and how to configure the refresh interval, refer to Syncing.

    If an unauthorized error is returned while attempting to modify or register the cluster and the cluster was not created with the role or user that your credentials belong to, refer to Security and Compliance.

    For any issues or troubleshooting details for your Amazon EKS Kubernetes cluster, please see this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/authentication-config.html b/v2.5/pages-for-subheaders/authentication-config.html index 00ff6fdd79c..69697fd5135 100644 --- a/v2.5/pages-for-subheaders/authentication-config.html +++ b/v2.5/pages-for-subheaders/authentication-config.html @@ -5,13 +5,13 @@ Authentication Config | Rancher Manager - +
    Version: v2.5

    Authentication Config

    In the following tutorials, you will learn how to manage users and groups, create local users, configure Google OAuth, configure Active Directory (AD), configure OpenLDAP, configure FreeIPA, configure Azure AD, configure GitHub, configure Keycloak, configure PingIdentity (SAML), configure Okta (SAML), configure Shibboleth (SAML), and how to configure Microsoft AD Federation Service (SAML).

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/authentication-permissions-and-global-configuration.html b/v2.5/pages-for-subheaders/authentication-permissions-and-global-configuration.html index 0a8f95b75cf..f71d0415a67 100644 --- a/v2.5/pages-for-subheaders/authentication-permissions-and-global-configuration.html +++ b/v2.5/pages-for-subheaders/authentication-permissions-and-global-configuration.html @@ -5,13 +5,13 @@ Authentication, Permissions and Global Configuration | Rancher Manager - +
    Version: v2.5

    Authentication, Permissions and Global Configuration

    After installation, the system administrator should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.

    First Log In​

    After you log into Rancher for the first time, Rancher will prompt you for a Rancher Server URL.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.

    Important! After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.

    Authentication​

    One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.

    For more information how authentication works and how to configure each provider, see Authentication.

    Authorization​

    Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.

    For more information how authorization works and how to customize roles, see Roles Based Access Control (RBAC).

    Pod Security Policies​

    Pod Security Policies (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.

    For more information how to create and use PSPs, see Pod Security Policies.

    Provisioning Drivers​

    Drivers in Rancher allow you to manage which providers can be used to provision hosted Kubernetes clusters or nodes in an infrastructure provider to allow Rancher to deploy and manage Kubernetes.

    For more information, see Provisioning Drivers.

    Adding Kubernetes Versions into Rancher​

    With this feature, you can upgrade to the latest version of Kubernetes as soon as it is released, without upgrading Rancher. This feature allows you to easily upgrade Kubernetes patch versions (i.e. v1.15.X), but not intended to upgrade Kubernetes minor versions (i.e. v1.X.0) as Kubernetes tends to deprecate or add APIs between minor versions.

    The information that Rancher uses to provision RKE clusters is now located in the Rancher Kubernetes Metadata. For details on metadata configuration and how to change the Kubernetes version used for provisioning RKE clusters, see Rancher Kubernetes Metadata.

    Rancher Kubernetes Metadata contains Kubernetes version information which Rancher uses to provision RKE clusters.

    For more information on how metadata works and how to configure metadata config, see Rancher Kubernetes Metadata.

    Enabling Experimental Features​

    Rancher includes some features that are experimental and disabled by default. Feature flags were introduced to allow you to try these features. For more information, refer to the section about feature flags.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/backup-restore-and-disaster-recovery.html b/v2.5/pages-for-subheaders/backup-restore-and-disaster-recovery.html index 8fc08a4ef56..e2827a936a6 100644 --- a/v2.5/pages-for-subheaders/backup-restore-and-disaster-recovery.html +++ b/v2.5/pages-for-subheaders/backup-restore-and-disaster-recovery.html @@ -5,13 +5,13 @@ Backups and Disaster Recovery | Rancher Manager - +
    Version: v2.5

    Backups and Disaster Recovery

    In this section, you'll learn how to create backups of Rancher, how to restore Rancher from backup, and how to migrate Rancher to a new Kubernetes cluster.

    As of Rancher v2.5, the rancher-backup operator is used to backup and restore Rancher. The rancher-backup Helm chart is here.

    The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.

    When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made.

    Changes in Rancher v2.5​

    The new rancher-backup operator allows Rancher to be backed up and restored on any Kubernetes cluster. This application is a Helm chart, and it can be deployed through the Rancher Apps & Marketplace page, or by using the Helm CLI.

    Previously, the way that cluster data was backed up depended on the type of Kubernetes cluster that was used.

    In Rancher v2.4, it was only supported to install Rancher on two types of Kubernetes clusters: an RKE cluster, or a K3s cluster with an external database. If Rancher was installed on an RKE cluster, RKE would be used to take a snapshot of the etcd database and restore the cluster. If Rancher was installed on a K3s cluster with an external database, the database would need to be backed up and restored using the upstream documentation for the database.

    In Rancher v2.5, it is now supported to install Rancher hosted Kubernetes clusters, such as Amazon EKS clusters, which do not expose etcd to a degree that would allow snapshots to be created by an external tool. etcd doesn't need to be exposed for rancher-backup to work, because the operator gathers resources by making calls to kube-apiserver.

    Backup and Restore for Rancher v2.5 installed with Docker​

    For Rancher installed with Docker, refer to the same steps used up till 2.5 for backups and restores.

    How Backups and Restores Work​

    The rancher-backup operator introduces three custom resources: Backups, Restores, and ResourceSets. The following cluster-scoped custom resource definitions are added to the cluster:

    • backups.resources.cattle.io
    • resourcesets.resources.cattle.io
    • restores.resources.cattle.io

    The ResourceSet defines which Kubernetes resources need to be backed up. The ResourceSet is not available to be configured in the Rancher UI because the values required to back up Rancher are predefined. This ResourceSet should not be modified.

    When a Backup custom resource is created, the rancher-backup operator calls the kube-apiserver to get the resources in the ResourceSet (specifically, the predefined rancher-resource-set) that the Backup custom resource refers to.

    The operator then creates the backup file in the .tar.gz format and stores it in the location configured in the Backup resource.

    When a Restore custom resource is created, the operator accesses the backup .tar.gz file specified by the Restore, and restores the application from that file.

    The Backup and Restore custom resources can be created in the Rancher UI, or by using kubectl apply.

    Installing the rancher-backup Operator​

    The rancher-backup operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the rancher-backup Helm chart is installed on the Kubernetes cluster running the Rancher server. It is a cluster-admin only feature and available only for the local cluster. (If you do not see rancher-backup in the Rancher UI, you may have selected the wrong cluster.)

    NOTE: There are two known issues in Fleet that occur after performing a restoration using the backup-restore-operator: Fleet agents are inoperable and clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer here for workarounds.

    Installing rancher-backup with the Rancher UI​

    1. In the Rancher UI's Cluster Manager, choose the cluster named local
    2. On the upper-right click on the Cluster Explorer.
    3. Click Apps.
    4. Click the rancher-backup operator.
    5. Optional: Configure the default storage location. For help, refer to the configuration section.

    Result: The rancher-backup operator is installed.

    From the Cluster Explorer, you can see the rancher-backup operator listed under Deployments.

    To configure the backup app in Rancher, click Cluster Explorer in the upper left corner and click Rancher Backups.

    Installing rancher-backup with the Helm CLI​

    Install the backup app as a Helm chart:

    helm repo add rancher-charts https://charts.rancher.io
    helm repo update
    helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace
    helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system

    RBAC​

    Only the rancher admins and the local cluster’s cluster-owner can:

    • Install the Chart
    • See the navigation links for Backup and Restore CRDs
    • Perform a backup or restore by creating a Backup CR and Restore CR respectively
    • List backups/restores performed so far

    Backing up Rancher​

    A backup is performed by creating a Backup custom resource. For a tutorial, refer to this page.

    Restoring Rancher​

    A restore is performed by creating a Restore custom resource. For a tutorial, refer to this page.

    Migrating Rancher to a New Cluster​

    A migration is performed by following these steps.

    Default Storage Location Configuration​

    Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible or Minio object store.

    For information on configuring these options, refer to this page.

    Example values.yaml for the rancher-backup Helm Chart​

    The example values.yaml file can be used to configure the rancher-backup operator when the Helm CLI is used to install it.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/backup-restore-configuration.html b/v2.5/pages-for-subheaders/backup-restore-configuration.html index 7a00b033123..6f54f291639 100644 --- a/v2.5/pages-for-subheaders/backup-restore-configuration.html +++ b/v2.5/pages-for-subheaders/backup-restore-configuration.html @@ -5,13 +5,13 @@ Rancher Backup Configuration Reference | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/best-practices.html b/v2.5/pages-for-subheaders/best-practices.html index 18f02748923..b3e6b27b5c8 100644 --- a/v2.5/pages-for-subheaders/best-practices.html +++ b/v2.5/pages-for-subheaders/best-practices.html @@ -5,13 +5,13 @@ Best Practices Guide | Rancher Manager - +
    Version: v2.5

    Best Practices Guide

    The purpose of this section is to consolidate best practices for Rancher implementations. This also includes recommendations for related technologies, such as Kubernetes, Docker, containers, and more. The objective is to improve the outcome of a Rancher implementation using the operational experience of Rancher and its customers.

    If you have any questions about how these might apply to your use case, please contact your Customer Success Manager or Support.

    Use the navigation bar on the left to find the current best practices for managing and deploying the Rancher Server.

    For more guidance on best practices, you can consult these resources:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/checklist-for-production-ready-clusters.html b/v2.5/pages-for-subheaders/checklist-for-production-ready-clusters.html index 1457fd989e9..a706d68a6ab 100644 --- a/v2.5/pages-for-subheaders/checklist-for-production-ready-clusters.html +++ b/v2.5/pages-for-subheaders/checklist-for-production-ready-clusters.html @@ -5,14 +5,14 @@ Checklist for Production-Ready Clusters | Rancher Manager - +
    Version: v2.5

    Checklist for Production-Ready Clusters

    In this section, we recommend best practices for creating the production-ready Kubernetes clusters that will run your apps and services.

    For a list of requirements for your cluster, including the requirements for OS/Docker, hardware, and networking, refer to the section on node requirements.

    This is a shortlist of best practices that we strongly recommend for all production clusters.

    For a full list of all the best practices that we recommend, refer to the best practices section.

    Node Requirements​

    • Make sure your nodes fulfill all of the node requirements, including the port requirements.

    Back up etcd​

    • Enable etcd snapshots. Verify that snapshots are being created, and run a disaster recovery scenario to verify the snapshots are valid. etcd is the location where the state of your cluster is stored, and losing etcd data means losing your cluster. Make sure you configure recurring snapshots of etcd for your cluster(s), and make sure the snapshots are stored externally (off the node) as well.

    Cluster Architecture​

    • Nodes should have one of the following role configurations:
      • etcd
      • controlplane
      • etcd and controlplane
      • worker (the worker role should not be used or added on nodes with the etcd or controlplane role)
    • Have at least three nodes with the role etcd to survive losing one node. Increase this count for higher node fault toleration, and spread them across (availability) zones to provide even better fault tolerance.
    • Assign two or more nodes the controlplane role for master component high availability.
    • Assign two or more nodes the worker role for workload rescheduling upon node failure.

    For more information on what each role is used for, refer to the section on roles for nodes in Kubernetes.

    For more information about the number of nodes for each Kubernetes role, refer to the section on recommended architecture.

    Logging and Monitoring​

    • Configure alerts/notifiers for Kubernetes components (System Service).
    • Configure logging for cluster analysis and post-mortems.

    Reliability​

    • Perform load tests on your cluster to verify that its hardware can support your workloads.

    Networking​

    • Minimize network latency. Rancher recommends minimizing latency between the etcd nodes. The default setting for heartbeat-interval is 500, and the default setting for election-timeout is 5000. These settings for etcd tuning allow etcd to run in most networks (except really high latency networks).
    • Cluster nodes should be located within a single region. Most cloud providers provide multiple availability zones within a region, which can be used to create higher availability for your cluster. Using multiple availability zones is fine for nodes with any role. If you are using Kubernetes Cloud Provider resources, consult the documentation for any restrictions (i.e. zone storage restrictions).
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/cis-scan-guides.html b/v2.5/pages-for-subheaders/cis-scan-guides.html index c990e569774..442fd140768 100644 --- a/v2.5/pages-for-subheaders/cis-scan-guides.html +++ b/v2.5/pages-for-subheaders/cis-scan-guides.html @@ -5,13 +5,13 @@ CIS Scan Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/cis-scans.html b/v2.5/pages-for-subheaders/cis-scans.html index 4c80b81342a..9d4f0fe35d0 100644 --- a/v2.5/pages-for-subheaders/cis-scans.html +++ b/v2.5/pages-for-subheaders/cis-scans.html @@ -5,13 +5,13 @@ CIS Scans | Rancher Manager - +
    Version: v2.5

    CIS Scans

    Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.

    The rancher-cis-benchmark app leverages kube-bench, an open-source tool from Aqua Security, to check clusters for CIS Kubernetes Benchmark compliance. Also, to generate a cluster-wide report, the application utilizes Sonobuoy for report aggregation.

    Changes in Rancher v2.5​

    We now support running CIS scans on any Kubernetes cluster, including hosted Kubernetes providers such as EKS, AKS, and GKE. Previously it was only supported to run CIS scans on RKE Kubernetes clusters.

    In Rancher v2.4, the CIS scan tool was available from the cluster manager in the Rancher UI. Now it is available in the Cluster Explorer and it can be enabled and deployed using a Helm chart. It can be installed from the Rancher UI, but it can also be installed independently of Rancher. It deploys a CIS scan operator for the cluster, and deploys Kubernetes custom resources for cluster scans. The custom resources can be managed directly from the Cluster Explorer.

    In v1 of the CIS scan tool, which was available in Rancher v2.4 through the cluster manager, recurring scans could be scheduled. The ability to schedule recurring scans is now also available for CIS v2 from Rancher v2.5.4.

    Support for alerting for the cluster scan results is now also available from Rancher v2.5.4.

    In Rancher v2.4, permissive and hardened profiles were included. In Rancher v2.5.0 and in v2.5.4, more profiles were included.

    • Generic CIS 1.5
    • Generic CIS 1.6
    • RKE permissive 1.5
    • RKE hardened 1.5
    • RKE permissive 1.6
    • RKE hardened 1.6
    • EKS
    • GKE
    • RKE2 permissive 1.5
    • RKE2 permissive 1.5

    The default profile and the supported CIS benchmark version depends on the type of cluster that will be scanned and the Rancher version:

    The rancher-cis-benchmark supports the CIS 1.6 Benchmark version.

    • For RKE Kubernetes clusters, the RKE Permissive 1.6 profile is the default.
    • EKS and GKE have their own CIS Benchmarks published by kube-bench. The corresponding test profiles are used by default for those clusters.
    • For RKE2 Kubernetes clusters, the RKE2 Permissive 1.5 profile is the default.
    • For cluster types other than RKE, RKE2, EKS and GKE, the Generic CIS 1.5 profile will be used by default.

    Note: CIS v1 cannot run on a cluster when CIS v2 is deployed. In other words, after rancher-cis-benchmark is installed, you can't run scans by going to the Cluster Manager view in the Rancher UI and clicking Tools > CIS Scans.

    About the CIS Benchmark​

    The Center for Internet Security is a 501(c)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace". The organization is headquartered in East Greenbush, New York, with members including large corporations, government agencies, and academic institutions.

    CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.

    The official Benchmark documents are available through the CIS website. The sign-up form to access the documents is

    here.

    About the Generated Report​

    Each scan generates a report can be viewed in the Rancher UI and can be downloaded in CSV format.

    From Rancher v2.5.4, the scan uses the CIS Benchmark v1.6 by default. In Rancher v2.5.0-2.5.3, the CIS Benchmark v1.5. is used.

    The Benchmark version is included in the generated report.

    The Benchmark provides recommendations of two types: Automated and Manual. Recommendations marked as Manual in the Benchmark are not included in the generated report.

    Some tests are designated as "Not Applicable." These tests will not be run on any CIS scan because of the way that Rancher provisions RKE clusters. For information on how test results can be audited, and why some tests are designated to be not applicable, refer to Rancher's self-assessment guide for the corresponding Kubernetes version.

    The report contains the following information:

    Column in ReportDescription
    idThe ID number of the CIS Benchmark.
    descriptionThe description of the CIS Benchmark test.
    remediationWhat needs to be fixed in order to pass the test.
    stateIndicates if the test passed, failed, was skipped, or was not applicable.
    node_typeThe node role, which affects which tests are run on the node. Master tests are run on controlplane nodes, etcd tests are run on etcd nodes, and node tests are run on the worker nodes.
    auditThis is the audit check that kube-bench runs for this test.
    audit_configAny configuration applicable to the audit script.
    test_infoTest-related info as reported by kube-bench, if any.
    commandsTest-related commands as reported by kube-bench, if any.
    config_commandsTest-related configuration data as reported by kube-bench, if any.
    actual_valueThe test's actual value, present if reported by kube-bench.
    expected_resultThe test's expected result, present if reported by kube-bench.

    Refer to the table in the cluster hardening guide for information on which versions of Kubernetes, the Benchmark, Rancher, and our cluster hardening guide correspond to each other. Also refer to the hardening guide for configuration files of CIS-compliant clusters and information on remediating failed tests.

    Test Profiles​

    The following profiles are available:

    • Generic CIS 1.5
    • Generic CIS 1.6
    • RKE permissive 1.5
    • RKE hardened 1.5
    • RKE permissive 1.6
    • RKE hardened 1.6
    • EKS
    • GKE
    • RKE2 permissive 1.5
    • RKE2 permissive 1.5

    You also have the ability to customize a profile by saving a set of tests to skip.

    All profiles will have a set of not applicable tests that will be skipped during the CIS scan. These tests are not applicable based on how a RKE cluster manages Kubernetes.

    There are two types of RKE cluster scan profiles:

    • Permissive: This profile has a set of tests that have been will be skipped as these tests will fail on a default RKE Kubernetes cluster. Besides the list of skipped tests, the profile will also not run the not applicable tests.
    • Hardened: This profile will not skip any tests, except for the non-applicable tests.

    The EKS and GKE cluster scan profiles are based on CIS Benchmark versions that are specific to those types of clusters.

    In order to pass the "Hardened" profile, you will need to follow the steps on the hardening guide and use the cluster.yml defined in the hardening guide to provision a hardened cluster.

    About Skipped and Not Applicable Tests​

    For a list of skipped and not applicable tests, refer to this page.

    For now, only user-defined skipped tests are marked as skipped in the generated report.

    Any skipped tests that are defined as being skipped by one of the default profiles are marked as not applicable.

    Roles-based Access Control​

    For information about permissions, refer to this page.

    Configuration​

    For more information about configuring the custom resources for the scans, profiles, and benchmark versions, refer to this page.

    How-to Guides​

    Please refer here for how-to guides on CIS scans.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/cli-with-rancher.html b/v2.5/pages-for-subheaders/cli-with-rancher.html index b63956b7454..e58b706e755 100644 --- a/v2.5/pages-for-subheaders/cli-with-rancher.html +++ b/v2.5/pages-for-subheaders/cli-with-rancher.html @@ -5,13 +5,13 @@ CLI with Rancher | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/cluster-configuration.html b/v2.5/pages-for-subheaders/cluster-configuration.html index 54c8278849a..8bd13303ba4 100644 --- a/v2.5/pages-for-subheaders/cluster-configuration.html +++ b/v2.5/pages-for-subheaders/cluster-configuration.html @@ -5,13 +5,13 @@ Cluster Configuration | Rancher Manager - +
    Version: v2.5

    Cluster Configuration

    After you provision a Kubernetes cluster using Rancher, you can still edit options and settings for the cluster.

    For information on editing cluster membership, go to this page.

    Cluster Configuration References​

    The cluster configuration options depend on the type of Kubernetes cluster:

    Cluster Management Capabilities by Cluster Type​

    The options and settings available for an existing cluster change based on the method that you used to provision it.

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher Launched Kubernetes ClustersEKS and GKE Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓
    Authorized Cluster Endpoint✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/configuration-options.html b/v2.5/pages-for-subheaders/configuration-options.html index d6c7ae76497..00c8bb168ef 100644 --- a/v2.5/pages-for-subheaders/configuration-options.html +++ b/v2.5/pages-for-subheaders/configuration-options.html @@ -5,13 +5,13 @@ Configuration Options | Rancher Manager - +
    Version: v2.5

    Configuration Options

    Egress Support​

    By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the overlay file.

    Enabling Automatic Sidecar Injection​

    Automatic sidecar injection is disabled by default. To enable this, set the sidecarInjectorWebhook.enableNamespacesByDefault=true in the values.yaml on install or upgrade. This automatically enables Istio sidecar injection into all new namespaces that are deployed.

    Overlay File​

    An Overlay File is designed to support extensive configuration of your Istio installation. It allows you to make changes to any values available in the IstioOperator API. This will ensure you can customize the default installation to fit any scenario.

    The Overlay File will add configuration on top of the default installation that is provided from the Istio chart installation. This means you do not need to redefine the components that already defined for installation.

    For more information on Overlay Files, refer to the Istio documentation.

    Selectors and Scrape Configs​

    The Monitoring app sets prometheus.prometheusSpec.ignoreNamespaceSelectors=false which enables monitoring across all namespaces by default. This ensures you can view traffic, metrics and graphs for resources deployed in a namespace with istio-injection=enabled label.

    If you would like to limit Prometheus to specific namespaces, set prometheus.prometheusSpec.ignoreNamespaceSelectors=true. Once you do this, you will need to add additional configuration to continue to monitor your resources.

    For details, refer to this section.

    Enable Istio with Pod Security Policies​

    Refer to this section.

    Additional Steps for Installing Istio on an RKE2 Cluster​

    Refer to this section.

    Additional Steps for Project Network Isolation​

    Refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html b/v2.5/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html index a0240ba6b3e..2af4a01dca8 100644 --- a/v2.5/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html +++ b/v2.5/pages-for-subheaders/configure-microsoft-ad-federation-service-saml.html @@ -5,13 +5,13 @@ Configuring Microsoft Active Directory Federation Service (SAML) | Rancher Manager - +
    Version: v2.5

    Configuring Microsoft Active Directory Federation Service (SAML)

    If your organization uses Microsoft Active Directory Federation Services (AD FS) for user authentication, you can configure Rancher to allow your users to log in using their AD FS credentials.

    Prerequisites​

    You must have Rancher installed.

    • Obtain your Rancher Server URL. During AD FS configuration, substitute this URL for the <RANCHER_SERVER> placeholder.
    • You must have a global administrator account on your Rancher installation.

    You must have a Microsoft AD FS Server configured.

    • Obtain your AD FS Server IP/DNS name. During AD FS configuration, substitute this IP/DNS name for the <AD_SERVER> placeholder.
    • You must have access to add Relying Party Trusts on your AD FS Server.

    Setup Outline​

    Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on your Active Directory server, and configuring Rancher to utilize your AD FS server. The following pages serve as guides for setting up Microsoft AD FS authentication on your Rancher installation.

    SAML Provider Caveats:
    • SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    Next: Configuring Microsoft AD FS for Rancher​

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/configure-openldap.html b/v2.5/pages-for-subheaders/configure-openldap.html index 1224819fcfb..c894bb3dcc9 100644 --- a/v2.5/pages-for-subheaders/configure-openldap.html +++ b/v2.5/pages-for-subheaders/configure-openldap.html @@ -5,13 +5,13 @@ Configuring OpenLDAP | Rancher Manager - +
    Version: v2.5

    Configuring OpenLDAP

    If your organization uses LDAP for user authentication, you can configure Rancher to communicate with an OpenLDAP server to authenticate users. This allows Rancher admins to control access to clusters and projects based on users and groups managed externally in the organisation's central user repository, while allowing end-users to authenticate with their LDAP credentials when logging in to the Rancher UI.

    Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognised certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. Log into the Rancher UI using the initial local admin account.
    2. From the Global view, navigate to Security > Authentication
    3. Select OpenLDAP. The Configure an OpenLDAP server form will be displayed.

    Test Authentication​

    Once you have completed the configuration, proceed by testing the connection to the OpenLDAP server. Authentication with OpenLDAP will be enabled implicitly if the test is successful.

    Note:

    The OpenLDAP user pertaining to the credentials entered in this step will be mapped to the local principal account and assigned administrator privileges in Rancher. You should therefore make a conscious decision on which LDAP account you use to perform this step.

    1. Enter the username and password for the OpenLDAP account that should be mapped to the local principal account.
    2. Click Authenticate With OpenLDAP to test the OpenLDAP connection and finalise the setup.

    Result:

    • OpenLDAP authentication is configured.
    • The LDAP user pertaining to the entered credentials is mapped to the local principal (administrative) account.

    Note:

    You will still be able to login using the locally configured admin account and password in case of a disruption of LDAP services.

    Annex: Troubleshooting​

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/configure-shibboleth-saml.html b/v2.5/pages-for-subheaders/configure-shibboleth-saml.html index f2cb8a63687..9671a90bd3e 100644 --- a/v2.5/pages-for-subheaders/configure-shibboleth-saml.html +++ b/v2.5/pages-for-subheaders/configure-shibboleth-saml.html @@ -5,7 +5,7 @@ Configuring Shibboleth (SAML) | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Configuring Shibboleth (SAML)

    If your organization uses Shibboleth Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in to Rancher using their Shibboleth credentials.

    In this configuration, when Rancher users log in, they will be redirected to the Shibboleth IdP to enter their credentials. After authentication, they will be redirected back to the Rancher UI.

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then the authenticated user will be able to access resources in Rancher that their groups have permissions for.

    The instructions in this section assume that you understand how Rancher, Shibboleth, and OpenLDAP work together. For a more detailed explanation of how it works, refer to this page.

    Setting up Shibboleth in Rancher

    Shibboleth Prerequisites​

    • You must have a Shibboleth IdP Server configured.
    • Following are the Rancher Service Provider URLs needed for configuration: Metadata URL: https://<rancher-server>/v1-saml/shibboleth/saml/metadata Assertion Consumer Service (ACS) URL: https://<rancher-server>/v1-saml/shibboleth/saml/acs
    • Export a metadata.xml file from your IdP Server. For more information, see the Shibboleth documentation.

    Configure Shibboleth in Rancher​

    If your organization uses Shibboleth for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.

    1. From the Global view, select Security > Authentication from the main menu.

    2. Select Shibboleth.

    3. Complete the Configure Shibboleth Account form. Shibboleth IdP lets you specify what data store you want to use. You can either add a database or use an existing ldap server. For example, if you select your Active Directory (AD) server, the examples below describe how you can map AD attributes to fields within Rancher.

      1. Display Name Field: Enter the AD attribute that contains the display name of users (example: displayName).

      2. User Name Field: Enter the AD attribute that contains the user name/given name (example: givenName).

      3. UID Field: Enter an AD attribute that is unique to every user (example: sAMAccountName, distinguishedName).

      4. Groups Field: Make entries for managing group memberships (example: memberOf).

      5. Rancher API Host: Enter the URL for your Rancher Server.

      6. Private Key and Certificate: This is a key-certificate pair to create a secure shell between Rancher and your IdP.

        You can generate one using an openssl command. For example:

        openssl req -x509 -newkey rsa:2048 -keyout myservice.key -out myservice.cert -days 365 -nodes -subj "/CN=myservice.example.com"

      7. IDP-metadata: The metadata.xml file that you exported from your IdP server.

    1. After you complete the Configure Shibboleth Account form, click Authenticate with Shibboleth, which is at the bottom of the page.

      Rancher redirects you to the IdP login page. Enter credentials that authenticate with Shibboleth IdP to validate your Rancher Shibboleth configuration.

      Note: You may have to disable your popup blocker to see the IdP login page.

    Result: Rancher is configured to work with Shibboleth. Your users can now sign into Rancher using their Shibboleth logins.

    SAML Provider Caveats​

    If you configure Shibboleth without OpenLDAP, the following caveats apply due to the fact that SAML Protocol does not support search or lookup for users or groups.

    • There is no validation on users or groups when assigning permissions to them in Rancher.
    • When adding users, the exact user IDs (i.e. UID Field) must be entered correctly. As you type the user ID, there will be no search for other user IDs that may match.
    • When adding groups, you must select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
    • The group drop-down shows only the groups that you are a member of. You will not be able to add groups that you are not a member of.

    To enable searching for groups when assigning permissions in Rancher, you will need to configure a back end for the SAML provider that supports groups, such as OpenLDAP.

    Setting up OpenLDAP in Rancher

    If you also configure OpenLDAP as the back end to Shibboleth, it will return a SAML assertion to Rancher with user attributes that include groups. Then authenticated users will be able to access resources in Rancher that their groups have permissions for.

    OpenLDAP Prerequisites​

    Rancher must be configured with a LDAP bind account (aka service account) to search and retrieve LDAP entries pertaining to users and groups that should have access. It is recommended to not use an administrator account or personal account for this purpose and instead create a dedicated account in OpenLDAP with read-only access to users and groups under the configured search base (see below).

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    Configure OpenLDAP in Rancher​

    Configure the settings for the OpenLDAP server, groups and users. For help filling out each field, refer to the configuration reference. Note that nested group membership is not available for Shibboleth.

    Before you proceed with the configuration, please familiarise yourself with the concepts of External Authentication Configuration and Principal Users.

    1. Log into the Rancher UI using the initial local admin account.
    2. From the Global view, navigate to Security > Authentication
    3. Select OpenLDAP. The Configure an OpenLDAP server form will be displayed.

    Troubleshooting

    If you are experiencing issues while testing the connection to the OpenLDAP server, first double-check the credentials entered for the service account as well as the search base configuration. You may also inspect the Rancher logs to help pinpointing the problem cause. Debug logs may contain more detailed information about the error. Please refer to How can I enable debug logging in this documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/create-kubernetes-persistent-storage.html b/v2.5/pages-for-subheaders/create-kubernetes-persistent-storage.html index b04e10ab335..1d51d10c971 100644 --- a/v2.5/pages-for-subheaders/create-kubernetes-persistent-storage.html +++ b/v2.5/pages-for-subheaders/create-kubernetes-persistent-storage.html @@ -5,13 +5,13 @@ Kubernetes Persistent Storage: Volumes and Storage Classes | Rancher Manager - +
    Version: v2.5

    Kubernetes Persistent Storage: Volumes and Storage Classes

    When deploying an application that needs to retain data, you'll need to create persistent storage. Persistent storage allows you to store application data external from the pod running your application. This storage practice allows you to maintain application data, even if the application's pod fails.

    The documents in this section assume that you understand the Kubernetes concepts of persistent volumes, persistent volume claims, and storage classes. For more information, refer to the section on how storage works.

    Prerequisites​

    To set up persistent storage, the Manage Volumes role is required.

    If you are provisioning storage for a cluster hosted in the cloud, the storage and cluster hosts must have the same cloud provider.

    For provisioning new storage with Rancher, the cloud provider must be enabled. For details on enabling cloud providers, refer to this page.

    For attaching existing persistent storage to a cluster, the cloud provider does not need to be enabled.

    Setting up Existing Storage​

    The overall workflow for setting up existing storage is as follows:

    1. Set up your persistent storage. This may be storage in an infrastructure provider, or it could be your own storage.
    2. Add a persistent volume (PV) that refers to the persistent storage.
    3. Add a persistent volume claim (PVC) that refers to the PV.
    4. Mount the PVC as a volume in your workload.

    For details and prerequisites, refer to this page.

    Dynamically Provisioning New Storage in Rancher​

    The overall workflow for provisioning new storage is as follows:

    1. Add a StorageClass and configure it to use your storage provider. The StorageClass could refer to storage in an infrastructure provider, or it could refer to your own storage.
    2. Add a persistent volume claim (PVC) that refers to the storage class.
    3. Mount the PVC as a volume for your workload.

    For details and prerequisites, refer to this page.

    Longhorn Storage​

    Longhorn is a lightweight, reliable and easy-to-use distributed block storage system for Kubernetes.

    Longhorn is free, open source software. Originally developed by Rancher Labs, it is now being developed as a sandbox project of the Cloud Native Computing Foundation. It can be installed on any Kubernetes cluster with Helm, with kubectl, or with the Rancher UI.

    If you have a pool of block storage, Longhorn can help you provide persistent storage to your Kubernetes cluster without relying on cloud providers. For more information about Longhorn features, refer to the documentation.

    Rancher v2.5 simplified the process of installing Longhorn on a Rancher-managed cluster. For more information, see this page.

    Provisioning Storage Examples​

    We provide examples of how to provision storage with NFS, vSphere, and Amazon's EBS.

    GlusterFS Volumes​

    In clusters that store data on GlusterFS volumes, you may experience an issue where pods fail to mount volumes after restarting the kubelet. For details on preventing this from happening, refer to this page.

    iSCSI Volumes​

    In Rancher Launched Kubernetes clusters that store data on iSCSI volumes, you may experience an issue where kubelets fail to automatically connect with iSCSI volumes. For details on resolving this issue, refer to this page.

    hostPath Volumes​

    Before you create a hostPath volume, you need to set up an extra_bind in your cluster configuration. This will mount the path as a volume in your kubelets, which can then be used for hostPath volumes in your workloads.

    Migrating vSphere Cloud Provider from In-tree to Out-of-tree​

    Kubernetes is moving away from maintaining cloud providers in-tree. vSphere has an out-of-tree cloud provider that can be used by installing the vSphere cloud provider and cloud storage plugins.

    For instructions on how to migrate from the in-tree vSphere cloud provider to out-of-tree, and manage the existing VMs post migration, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/custom-resource-configuration.html b/v2.5/pages-for-subheaders/custom-resource-configuration.html index 384e468ca2e..413567a9eff 100644 --- a/v2.5/pages-for-subheaders/custom-resource-configuration.html +++ b/v2.5/pages-for-subheaders/custom-resource-configuration.html @@ -5,13 +5,13 @@ Custom Resource Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/deploy-apps-across-clusters.html b/v2.5/pages-for-subheaders/deploy-apps-across-clusters.html index 1fe5b095bb6..0c094720646 100644 --- a/v2.5/pages-for-subheaders/deploy-apps-across-clusters.html +++ b/v2.5/pages-for-subheaders/deploy-apps-across-clusters.html @@ -5,13 +5,13 @@ Deploying Applications across Clusters | Rancher Manager - +
    Version: v2.5

    Deploying Applications across Clusters

    Fleet​

    Rancher v2.5 introduced Fleet, a new way to deploy applications across clusters.

    Fleet is GitOps at scale. For more information, refer to the Fleet section.

    Multi-cluster Apps​

    In Rancher before v2.5, the multi-cluster apps feature was used to deploy applications across clusters. The multi-cluster apps feature is deprecated, but still available in Rancher v2.5.

    Refer to the documentation here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/deploy-rancher-manager.html b/v2.5/pages-for-subheaders/deploy-rancher-manager.html index 3191dbdd120..58ac2fc7263 100644 --- a/v2.5/pages-for-subheaders/deploy-rancher-manager.html +++ b/v2.5/pages-for-subheaders/deploy-rancher-manager.html @@ -5,13 +5,13 @@ Deploying Rancher Server | Rancher Manager - +
    Version: v2.5

    Deploying Rancher Server

    Use one of the following guides to deploy and provision Rancher and a Kubernetes cluster in the provider of your choice.

    If you prefer, the following guide will take you through the same process in individual steps. Use this if you want to run Rancher in a different provider, on prem, or if you would just like to see how easy it is.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/deploy-rancher-workloads.html b/v2.5/pages-for-subheaders/deploy-rancher-workloads.html index 1d5e56e0933..8409bd92ad7 100644 --- a/v2.5/pages-for-subheaders/deploy-rancher-workloads.html +++ b/v2.5/pages-for-subheaders/deploy-rancher-workloads.html @@ -5,13 +5,13 @@ Deploying Workloads | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/downstream-cluster-configuration.html b/v2.5/pages-for-subheaders/downstream-cluster-configuration.html index 9388fc3e828..9af6d4cb70e 100644 --- a/v2.5/pages-for-subheaders/downstream-cluster-configuration.html +++ b/v2.5/pages-for-subheaders/downstream-cluster-configuration.html @@ -5,13 +5,13 @@ Downstream Cluster Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/enable-experimental-features.html b/v2.5/pages-for-subheaders/enable-experimental-features.html index 3c168c83018..329664e8c2f 100644 --- a/v2.5/pages-for-subheaders/enable-experimental-features.html +++ b/v2.5/pages-for-subheaders/enable-experimental-features.html @@ -5,13 +5,13 @@ Enabling Experimental Features | Rancher Manager - +
    Version: v2.5

    Enabling Experimental Features

    Rancher includes some features that are experimental and disabled by default. You might want to enable these features, for example, if you decide that the benefits of using an unsupported storage type outweighs the risk of using an untested feature. Feature flags were introduced to allow you to try these features that are not enabled by default.

    The features can be enabled in three ways:

    Each feature has two values:

    • A default value, which can be configured with a flag or environment variable from the command line
    • A set value, which can be configured with the Rancher API or UI

    If no value has been set, Rancher uses the default value.

    Because the API sets the actual value and the command line sets the default value, that means that if you enable or disable a feature with the API or UI, it will override any value set with the command line.

    For example, if you install Rancher, then set a feature flag to true with the Rancher API, then upgrade Rancher with a command that sets the feature flag to false, the default value will still be false, but the feature will still be enabled because it was set with the Rancher API. If you then deleted the set value (true) with the Rancher API, setting it to NULL, the default value (false) would take effect. See the feature flags page for more information.

    Enabling Features when Starting Rancher

    When you install Rancher, enable the feature you want with a feature flag. The command is different depending on whether you are installing Rancher on a single node or if you are doing a Kubernetes Installation of Rancher.

    Enabling Features for Kubernetes Installs​

    note

    Values set from the Rancher API will override the value passed in through the command line.

    When installing Rancher with a Helm chart, use the --set option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

    helm install rancher rancher-latest/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set 'extraEnv[0].name=CATTLE_FEATURES'
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'
    note

    If you are installing an alpha version, Helm requires adding the --devel option to the command.

    Rendering the Helm Chart for Air Gap Installations​

    For an air gap installation of Rancher, you need to add a Helm chart repository and render a Helm template before installing Rancher with Helm. For details, refer to the air gap installation documentation.

    Here is an example of a command for passing in the feature flag names when rendering the Helm template. In the below example, two features are enabled by passing the feature flag names in a comma separated list.

    The Helm command is as follows:

    helm template rancher ./rancher-<VERSION>.tgz --output-dir . \
      --no-hooks \ # prevent files for Helm hooks from being generated
      --namespace cattle-system \
      --set hostname=<RANCHER.YOURDOMAIN.COM> \
      --set rancherImage=<REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher \
      --set ingress.tls.source=secret \
      --set systemDefaultRegistry=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
      --set useBundledSystemChart=true # Use the packaged Rancher system charts
      --set 'extraEnv[0].name=CATTLE_FEATURES'
      --set 'extraEnv[0].value=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true'

    Enabling Features for Docker Installs​

    When installing Rancher with Docker, use the --features option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:

    docker run -d -p 80:80 -p 443:443 \
      --restart=unless-stopped \
      rancher/rancher:rancher-latest \
      --features=<FEATURE-FLAG-NAME-1>=true,<FEATURE-FLAG-NAME-2>=true

    Enabling Features with the Rancher UI

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags.
    3. To enable a feature, go to the disabled feature you want to enable and click ⋮ > Activate.

    Result: The feature is enabled.

    Disabling Features with the Rancher UI​

    1. In the upper left corner, click ☰ > Global Settings.
    2. Click Feature Flags. You will see a list of experimental features.
    3. To disable a feature, go to the enabled feature you want to disable and click ⋮ > Deactivate.

    Result: The feature is disabled.

    Enabling Features with the Rancher API

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click True.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is enabled.

    Disabling Features with the Rancher API​

    1. Go to <RANCHER-SERVER-URL>/v3/features.
    2. In the data section, you will see an array containing all of the features that can be turned on with feature flags. The name of the feature is in the id field. Click the name of the feature you want to enable.
    3. In the upper left corner of the screen, under Operations, click Edit.
    4. In the Value drop-down menu, click False.
    5. Click Show Request.
    6. Click Send Request.
    7. Click Close.

    Result: The feature is disabled.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/fleet-gitops-at-scale.html b/v2.5/pages-for-subheaders/fleet-gitops-at-scale.html index 7ea1b70b246..ebec283565e 100644 --- a/v2.5/pages-for-subheaders/fleet-gitops-at-scale.html +++ b/v2.5/pages-for-subheaders/fleet-gitops-at-scale.html @@ -5,13 +5,13 @@ Fleet - GitOps at Scale | Rancher Manager - +
    Version: v2.5

    Fleet - GitOps at Scale

    Available as of Rancher v2.5

    Fleet is GitOps at scale. Fleet is designed to manage up to a million clusters. It’s also lightweight enough that it works great for a single cluster too, but it really shines when you get to a large scale. By large scale we mean either a lot of clusters, a lot of deployments, or a lot of teams in a single organization.

    Fleet is a separate project from Rancher, and can be installed on any Kubernetes cluster with Helm.

    Architecture​

    For information about how Fleet works, see this page.

    Accessing Fleet in the Rancher UI​

    Fleet comes preinstalled in Rancher v2.5. Users can leverage continuous delivery to deploy their applications to the Kubernetes clusters in the git repository without any manual operation by following gitops practice. For additional information on Continuous Delivery and other Fleet troubleshooting tips, refer here.

    Follow the steps below to access Continuous Delivery in the Rancher UI:

    1. Click Cluster Explorer in the Rancher UI.

    2. In the top left dropdown menu, click Cluster Explorer > Continuous Delivery.

    3. Select your namespace at the top of the menu, noting the following:

      • By default, fleet-default is selected which includes all downstream clusters that are registered through Rancher.

      • You may switch to fleet-local, which only contains the local cluster, or you may create your own workspace to which you may assign and move clusters.

      • You can then manage clusters by clicking on Clusters on the left navigation bar.

    4. Click on Gitrepos on the left navigation bar to deploy the gitrepo into your clusters in the current workspace.

    5. Select your git repository and target clusters/cluster group. You can also create the cluster group in the UI by clicking on Cluster Groups from the left navigation bar.

    6. Once the gitrepo is deployed, you can monitor the application through the Rancher UI.

    Windows Support​

    Available as of v2.5.6

    For details on support for clusters with Windows nodes, see this page.

    GitHub Repository​

    The Fleet Helm charts are available here.

    Using Fleet Behind a Proxy​

    Available as of v2.5.8

    For details on using Fleet behind a proxy, see this page.

    Helm Chart Dependencies​

    In order for Helm charts with dependencies to deploy successfully, you must run a manual command (as listed below), as it is up to the user to fulfill the dependency list. If you do not do this and proceed to clone your repository and run helm install, your installation will fail because the dependencies will be missing.

    The Helm chart in the git repository must include its dependencies in the charts subdirectory. You must either manually run helm dependencies update $chart OR run helm dependencies build $chart locally, then commit the complete charts directory to your git repository. Note that you will update your commands with the applicable parameters

    Troubleshooting​

    • Known Issue: Fleet becomes inoperable after a restore using the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround:

      1. Find the two service account tokens listed in the fleet-controller and the fleet-controller-bootstrap service accounts. These are under the fleet-system namespace of the local cluster.
      2. Remove the non-existent token secret. Doing so allows for only one entry to be present for the service account token secret that actually exists.
      3. Delete the fleet-controller Pod in the fleet-system namespace to reschedule.
      4. After the service account token issue is resolved, you can force redeployment of the fleet-agents. In the Rancher UI, go to ☰ > Cluster Management, click on Clusters page, then click Force Update.
      5. If the fleet-agent bundles remain in a Modified state after Step 4, update the field spec.forceSyncGeneration for the fleet-agent bundle to force re-creation.

    • Known Issue: clientSecretName and helmSecretName secrets for Fleet gitrepos are not included in the backup nor restore created by the backup-restore-operator. We will update the community once a permanent solution is in place.

    • Temporary Workaround: By default, user-defined secrets are not backed up in Fleet. It is necessary to recreate secrets if performing a disaster recovery restore or migration of Rancher into a fresh cluster. To modify resourceSet to include extra resources you want to backup, refer to docs here.

    Documentation​

    The Fleet documentation is at https://fleet.rancher.io/.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/gke-cluster-configuration.html b/v2.5/pages-for-subheaders/gke-cluster-configuration.html index 1649cefc6b7..5d1a15dee81 100644 --- a/v2.5/pages-for-subheaders/gke-cluster-configuration.html +++ b/v2.5/pages-for-subheaders/gke-cluster-configuration.html @@ -5,13 +5,13 @@ GKE Cluster Configuration Reference | Rancher Manager - +
    Version: v2.5

    GKE Cluster Configuration Reference

    Changes in v2.5.8

    • We now support private GKE clusters. Note: This advanced setup can require more steps during the cluster provisioning process. For details, see this section.
    • Shared VPCs are now supported.
    • We now support more configuration options for Rancher managed GKE clusters:
      • Project
      • Network policy
      • Network policy config
      • Node pools and node configuration options:
        • More image types are available for the nodes
        • The maximum number of pods per node can be configured
      • Node pools can be added while configuring the GKE cluster
    • When provisioning a GKE cluster, you can now use reusable cloud credentials instead of using a service account token directly to create the cluster.

    Cluster Location

    ValueDescription
    Location TypeZonal or Regional. With GKE, you can create a cluster tailored to the availability requirements of your workload and your budget. By default, a cluster's nodes run in a single compute zone. When multiple zones are selected, the cluster's nodes will span multiple compute zones, while the controlplane is located in a single zone. Regional clusters increase the availability of the controlplane as well. For help choosing the type of cluster availability, refer to these docs.
    ZoneEach region in Compute engine contains a number of zones. For more information about available regions and zones, refer to these docs.
    Additional ZonesFor zonal clusters, you can select additional zones to create a multi-zone cluster.
    RegionFor regional clusters, you can select a region. For more information about available regions and zones, refer to this section. The first part of each zone name is the name of the region.

    Cluster Options

    Kubernetes Version​

    Mutable: yes

    For more information on GKE Kubernetes versions, refer to these docs.

    Container Address Range​

    Mutable: no

    The IP address range for pods in the cluster. Must be a valid CIDR range, e.g. 10.42.0.0/16. If not specified, a random range is automatically chosen from 10.0.0.0/8 and will exclude ranges already allocated to VMs, other clusters, or routes. Automatically chosen ranges may conflict with reserved IP addresses, dynamic routes, or routes within VPCs peering with the cluster.

    Network​

    Mutable: no

    The Compute Engine Network that the cluster connects to. Routes and firewalls will be created using this network. If using Shared VPCs, the VPC networks that are shared to your project will appear here. will be available to select in this field. For more information, refer to this page.

    Node Subnet / Subnet​

    Mutable: no

    The Compute Engine subnetwork that the cluster connects to. This subnetwork must belong to the network specified in the Network field. Select an existing subnetwork, or select "Auto Create Subnetwork" to have one automatically created. If not using an existing network, Subnetwork Name is required to generate one. If using Shared VPCs, the VPC subnets that are shared to your project will appear here. If using a Shared VPC network, you cannot select "Auto Create Subnetwork". For more information, refer to this page.

    Subnetwork Name​

    Mutable: no

    Automatically create a subnetwork with the provided name. Required if "Auto Create Subnetwork" is selected for Node Subnet or Subnet. For more information on subnetworks, refer to this page.

    Ip Aliases​

    Mutable: no

    Enable alias IPs. This enables VPC-native traffic routing. Required if using Shared VPCs.

    Network Policy​

    Mutable: yes

    Enable network policy enforcement on the cluster. A network policy defines the level of communication that can occur between pods and services in the cluster. For more information, refer to this page.

    Node Ipv4 CIDR Block​

    Mutable: no

    The IP address range of the instance IPs in this cluster. Can be set if "Auto Create Subnetwork" is selected for Node Subnet or Subnet. Must be a valid CIDR range, e.g. 10.96.0.0/14. For more information on how to determine the IP address range, refer to this page.

    Cluster Secondary Range Name​

    Mutable: no

    The name of an existing secondary range for Pod IP addresses. If selected, Cluster Pod Address Range will automatically be populated. Required if using a Shared VPC network.

    Cluster Pod Address Range​

    Mutable: no

    The IP address range assigned to pods in the cluster. Must be a valid CIDR range, e.g. 10.96.0.0/11. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your pods, refer to this section.

    Services Secondary Range Name​

    Mutable: no

    The name of an existing secondary range for service IP addresses. If selected, Service Address Range will be automatically populated. Required if using a Shared VPC network.

    Service Address Range​

    Mutable: no

    The address range assigned to the services in the cluster. Must be a valid CIDR range, e.g. 10.94.0.0/18. If not provided, will be created automatically. Must be provided if using a Shared VPC network. For more information on how to determine the IP address range for your services, refer to this section.

    Private Cluster​

    Mutable: no

    Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the private cluster guide.

    Assign nodes only internal IP addresses. Private cluster nodes cannot access the public internet unless additional networking steps are taken in GCP.

    Enable Private Endpoint​

    Warning: private clusters require additional planning and configuration outside of Rancher. Refer to the private cluster guide.

    Mutable: no

    Locks down external access to the control plane endpoint. Only available if Private Cluster is also selected. If selected, and if Rancher does not have direct access to the Virtual Private Cloud network the cluster is running in, Rancher will provide a registration command to run on the cluster to enable Rancher to connect to it.

    Master IPV4 CIDR Block​

    Mutable: no

    The IP range for the control plane VPC.

    Master Authorized Network​

    Mutable: yes

    Enable control plane authorized networks to block untrusted non-GCP source IPs from accessing the Kubernetes master through HTTPS. If selected, additional authorized networks may be added. If the cluster is created with a public endpoint, this option is useful for locking down access to the public endpoint to only certain networks, such as the network where your Rancher service is running. If the cluster only has a private endpoint, this setting is required.

    Additional Options

    Cluster Addons​

    Additional Kubernetes cluster components. For more information, refer to this page.

    Horizontal Pod Autoscaling​

    Mutable: yes

    The Horizontal Pod Autoscaler changes the shape of your Kubernetes workload by automatically increasing or decreasing the number of Pods in response to the workload's CPU or memory consumption, or in response to custom metrics reported from within Kubernetes or external metrics from sources outside of your cluster. For more information, see this page.

    HTTP (L7) Load Balancing​

    Mutable: yes

    HTTP (L7) Load Balancing distributes HTTP and HTTPS traffic to backends hosted on GKE. For more information, refer to this page.

    Network Policy Config (master only)​

    Mutable: yes

    Configuration for NetworkPolicy. This only tracks whether the addon is enabled or not on the master, it does not track whether network policy is enabled for the nodes.

    Cluster Features (Alpha Features)​

    Mutable: no

    Turns on all Kubernetes alpha API groups and features for the cluster. When enabled, the cluster cannot be upgraded and will be deleted automatically after 30 days. Alpha clusters are not recommended for production use as they are not covered by the GKE SLA. For more information, refer to this page.

    Logging Service​

    Mutable: yes

    The logging service the cluster uses to write logs. Use either Cloud Logging or no logging service in which case no logs are exported from the cluster.

    Monitoring Service​

    Mutable: yes

    The monitoring service the cluster uses to write metrics. Use either Cloud Monitoring or monitoring service in which case no metrics are exported from the cluster.

    Maintenance Window​

    Mutable: yes

    Set the start time for a 4 hour maintenance window. The time is specified in the UTC time zone using the HH:MM format. For more information, refer to this page.

    Node Pools

    In this section, enter details describing the configuration of each node in the node pool.

    Kubernetes Version​

    Mutable: yes

    The Kubernetes version for each node in the node pool. For more information on GKE Kubernetes versions, refer to these docs.

    Image Type​

    Mutable: yes

    The node operating system image. For more information for the node image options that GKE offers for each OS, refer to this page.

    Note: the default option is "Container-Optimized OS with Docker". The read-only filesystem on GCP's Container-Optimized OS is not compatible with the legacy logging implementation in Rancher. If you need to use the legacy logging feature, select "Ubuntu with Docker" or "Ubuntu with Containerd". The logging feature as of v2.5 is compatible with the Container-Optimized OS image.

    Note: if selecting "Windows Long Term Service Channel" or "Windows Semi-Annual Channel" for the node pool image type, you must also add at least one Container-Optimized OS or Ubuntu node pool.

    Machine Type​

    Mutable: no

    The virtualized hardware resources available to node instances. For more information on Google Cloud machine types, refer to this page.

    Root Disk Type​

    Mutable: no

    Standard persistent disks are backed by standard hard disk drives (HDD), while SSD persistent disks are backed by solid state drives (SSD). For more information, refer to this section.

    Local SSD Disks​

    Mutable: no

    Configure each node's local SSD disk storage in GB. Local SSDs are physically attached to the server that hosts your VM instance. Local SSDs have higher throughput and lower latency than standard persistent disks or SSD persistent disks. The data that you store on a local SSD persists only until the instance is stopped or deleted. For more information, see this section.

    Preemptible nodes (beta)​

    Mutable: no

    Preemptible nodes, also called preemptible VMs, are Compute Engine VM instances that last a maximum of 24 hours in general, and provide no availability guarantees. For more information, see this page.

    Taints​

    Mutable: no

    When you apply a taint to a node, only Pods that tolerate the taint are allowed to run on the node. In a GKE cluster, you can apply a taint to a node pool, which applies the taint to all nodes in the pool.

    Node Labels​

    Mutable: no

    You can apply labels to the node pool, which applies the labels to all nodes in the pool.

    Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.

    Group Details

    In this section, enter details describing the node pool.

    Name​

    Mutable: no

    Enter a name for the node pool.

    Initial Node Count​

    Mutable: yes

    Integer for the starting number of nodes in the node pool.

    Max Pod Per Node​

    Mutable: no

    GKE has a hard limit of 110 Pods per node. For more information on the Kubernetes limits, see this section.

    Autoscaling​

    Mutable: yes

    Node pool autoscaling dynamically creates or deletes nodes based on the demands of your workload. For more information, see this page.

    Auto Repair​

    Mutable: yes

    GKE's node auto-repair feature helps you keep the nodes in your cluster in a healthy, running state. When enabled, GKE makes periodic checks on the health state of each node in your cluster. If a node fails consecutive health checks over an extended time period, GKE initiates a repair process for that node. For more information, see the section on auto-repairing nodes.

    Auto Upgrade​

    Mutable: yes

    When enabled, the auto-upgrade feature keeps the nodes in your cluster up-to-date with the cluster control plane (master) version when your control plane is updated on your behalf. For more information about auto-upgrading nodes, see this page.

    Access Scopes​

    Mutable: no

    Access scopes are the legacy method of specifying permissions for your nodes.

    • Allow default access: The default access for new clusters is the Compute Engine default service account.
    • Allow full access to all Cloud APIs: Generally, you can just set the cloud-platform access scope to allow full access to all Cloud APIs, then grant the service account only relevant IAM roles. The combination of access scopes granted to the virtual machine instance and the IAM roles granted to the service account determines the amount of access the service account has for that instance.
    • Set access for each API: Alternatively, you can choose to set specific scopes that permit access to the particular API methods that the service will call.

    For more information, see the section about enabling service accounts for a VM.

    Configuring the Refresh Interval​

    The refresh interval can be configured through the setting "gke-refresh", which is an integer representing seconds.

    The default value is 300 seconds.

    The syncing interval can be changed by running kubectl edit setting gke-refresh.

    The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for GCP APIs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/helm-charts-in-rancher.html b/v2.5/pages-for-subheaders/helm-charts-in-rancher.html index bb9c654a617..4fe01201a60 100644 --- a/v2.5/pages-for-subheaders/helm-charts-in-rancher.html +++ b/v2.5/pages-for-subheaders/helm-charts-in-rancher.html @@ -5,13 +5,13 @@ Helm Charts in Rancher | Rancher Manager - +
    Version: v2.5

    Helm Charts in Rancher

    In this section, you'll learn how to manage Helm chart repositories and applications in Rancher.

    Changes in Rancher v2.5​

    In Rancher v2.5, the Apps and Marketplace feature replaced the catalog system.

    In the cluster manager, Rancher uses a catalog system to import bundles of charts and then uses those charts to either deploy custom helm applications or Rancher's tools such as Monitoring or Istio. The catalog system is still available in the cluster manager in Rancher v2.5, but it is deprecated.

    Now in the Cluster Explorer, Rancher uses a similar but simplified version of the same system. Repositories can be added in the same way that catalogs were, but are specific to the current cluster. Rancher tools come as pre-loaded repositories which deploy as standalone helm charts.

    Charts​

    From the top-left menu select "Apps & Marketplace" and you will be taken to the Charts page.

    The charts page contains all Rancher, Partner, and Custom Charts.

    • Rancher tools such as Logging or Monitoring are included under the Rancher label
    • Partner charts reside under the Partners label
    • Custom charts will show up under the name of the repository

    All three types are deployed and managed in the same way.

    Apps managed by the Cluster Manager should continue to be managed only by the Cluster Manager, and apps managed with the Cluster Explorer must be managed only by the Cluster Explorer.

    Repositories​

    From the left sidebar select "Repositories".

    These items represent helm repositories, and can be either traditional helm endpoints which have an index.yaml, or git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository.

    To add a private CA for Helm Chart repositories:

    • HTTP-based chart repositories: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as openssl x509 -outform der -in ca.pem | base64 -w0. Click Edit YAML for the chart repo and set, as in the following example:

      [...]
      spec:
        caBundle:
      MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
      ...
      nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
      [...]

    • Git-based chart repositories: It is not currently possible to add a private CA. For git-based chart repositories with a certificate signed by a private CA, you must disable TLS verification. Click Edit YAML for the chart repo, and add the key/value pair as follows:

      [...]
      spec:
        insecureSkipTLSVerify: true
      [...]

    Note: Helm chart repositories with authentication

    As of Rancher v2.5.12, a new value disableSameOriginCheck has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL.

    To use this feature for an existing Helm chart repository, click ⋮ > Edit YAML. On the spec portion of the YAML file, add disableSameOriginCheck and set it to true.

    [...]
    spec:
      disableSameOriginCheck: true
    [...]

    Helm Compatibility​

    The Cluster Explorer only supports Helm 3 compatible charts.

    Deployment and Upgrades​

    From the "Charts" tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed.

    To view all recent changes, go to the "Recent Operations" tab. From there you can view the call that was made, conditions, events, and logs.

    After installing a chart, you can find it in the "Installed Apps" tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation.

    Most Rancher tools have additional pages located in the toolbar below the "Apps & Marketplace" section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information.

    If you are upgrading your chart using "Customize Helm options before upgrade" , please be aware that using the "--force" option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can:

    • use the default upgrade option ( i.e do not use "--force" option )
    • uninstall the existing chart and install the upgraded chart
    • delete the resources with immutable fields from the cluster before performing the "--force" upgrade
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/horizontal-pod-autoscaler.html b/v2.5/pages-for-subheaders/horizontal-pod-autoscaler.html index 5ba95304cdd..a0b1327c1c9 100644 --- a/v2.5/pages-for-subheaders/horizontal-pod-autoscaler.html +++ b/v2.5/pages-for-subheaders/horizontal-pod-autoscaler.html @@ -5,14 +5,14 @@ The Horizontal Pod Autoscaler | Rancher Manager - +
    Version: v2.5

    The Horizontal Pod Autoscaler

    The Horizontal Pod Autoscaler (HPA) is a Kubernetes feature that allows you to configure your cluster to automatically scale the services it's running up or down.

    Rancher provides some additional features to help manage HPAs, depending on the version of Rancher.

    You can create, manage, and delete HPAs using the Rancher UI. It only supports HPA in the autoscaling/v2beta2 API.

    Managing HPAs​

    The way that you manage HPAs is different based on your version of the Kubernetes API:

    • For Kubernetes API version autoscaling/V2beta1: This version of the Kubernetes API lets you autoscale your pods based on the CPU and memory utilization of your application.
    • For Kubernetes API Version autoscaling/V2beta2: This version of the Kubernetes API lets you autoscale your pods based on CPU and memory utilization, in addition to custom metrics.

    You can create, manage, and delete HPAs using the Rancher UI. From the Rancher UI you can configure the HPA to scale based on CPU and memory utilization. For more information, refer to Managing HPAs with the Rancher UI. To scale the HPA based on custom metrics, you still need to use kubectl. For more information, refer to Configuring HPA to Scale Using Custom Metrics with Prometheus.

    Clusters created in Rancher v2.0.7 and higher automatically have all the requirements needed (metrics-server and Kubernetes cluster configuration) to use HPA.

    Testing HPAs with a Service Deployment​

    You can see your HPA's current number of replicas by going to your project and clicking Resources > HPA. For more information, refer to Get HPA Metrics and Status.

    You can also use kubectl to get the status of HPAs that you test with your load testing tool. For more information, refer to [Testing HPAs with kubectl] (k8s-in-rancher/horitzontal-pod-autoscaler/testing-hpa/).

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/infrastructure-setup.html b/v2.5/pages-for-subheaders/infrastructure-setup.html index 4529608cd98..169c853d18f 100644 --- a/v2.5/pages-for-subheaders/infrastructure-setup.html +++ b/v2.5/pages-for-subheaders/infrastructure-setup.html @@ -5,13 +5,13 @@ Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
    Version: v2.5

    Don't have infrastructure for your Kubernetes cluster? Try one of these tutorials.

    To set up infrastructure for a high-availability K3s Kubernetes cluster with an external DB, refer to this page.

    To set up infrastructure for a high-availability RKE Kubernetes cluster, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/install-cluster-autoscaler.html b/v2.5/pages-for-subheaders/install-cluster-autoscaler.html index 47b7cd01041..f47c3666016 100644 --- a/v2.5/pages-for-subheaders/install-cluster-autoscaler.html +++ b/v2.5/pages-for-subheaders/install-cluster-autoscaler.html @@ -5,13 +5,13 @@ Cluster Autoscaler | Rancher Manager - +
    Version: v2.5

    Cluster Autoscaler

    In this section, you'll learn how to install and use the Kubernetes cluster-autoscaler on Rancher custom clusters using AWS EC2 Auto Scaling Groups.

    The cluster autoscaler is a tool that automatically adjusts the size of the Kubernetes cluster when one of the following conditions is true:

    • There are pods that failed to run in the cluster due to insufficient resources.
    • There are nodes in the cluster that have been underutilized for an extended period of time and their pods can be placed on other existing nodes.

    To prevent your pod from being evicted, set a priorityClassName: system-cluster-critical property on your pod spec.

    Cluster Autoscaler is designed to run on Kubernetes master nodes. It can run in the kube-system namespace. Cluster Autoscaler doesn't scale down nodes with non-mirrored kube-system pods running on them.

    It's possible to run a customized deployment of Cluster Autoscaler on worker nodes, but extra care needs to be taken to ensure that Cluster Autoscaler remains up and running.

    Cloud Providers

    Cluster Autoscaler provides support to distinct cloud providers. For more information, go to cluster-autoscaler supported cloud providers.

    Setting up Cluster Autoscaler on Amazon Cloud Provider​

    For details on running the cluster autoscaler on Amazon cloud provider, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/install-rancher-on-linux.html b/v2.5/pages-for-subheaders/install-rancher-on-linux.html index 719b80305a2..e958d757e46 100644 --- a/v2.5/pages-for-subheaders/install-rancher-on-linux.html +++ b/v2.5/pages-for-subheaders/install-rancher-on-linux.html @@ -5,13 +5,13 @@ Install/Upgrade Rancher with RancherD | Rancher Manager - +
    Version: v2.5

    Install/Upgrade Rancher with RancherD

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    We are excited to introduce a new, simpler way to install Rancher called RancherD.

    RancherD is a single binary that first launches an RKE2 Kubernetes cluster, then installs the Rancher server Helm chart on the cluster.

    About RancherD Installs

    When RancherD is launched on a host, it first installs an RKE2 Kubernetes cluster, then deploys Rancher on the cluster as a Kubernetes daemonset.

    In both the RancherD install and the Helm CLI install, Rancher is installed as a Helm chart on a Kubernetes cluster.

    Configuration and upgrading are also simplified with RancherD. When you upgrade the RancherD binary, both the Kubernetes cluster and the Rancher Helm chart are upgraded.

    In Part I of these instructions, you'll learn how to launch RancherD on a single node. The result of following the steps in Part I is a single-node RKE2 Kubernetes cluster with the Rancher server installed. This cluster can easily become high availability later. If Rancher only needs to manage the local Kubernetes cluster, the installation is complete.

    Part II explains how to convert the single-node Rancher installation into a high-availability installation. If the Rancher server will manage downstream Kubernetes clusters, it is important to follow these steps. A discussion of recommended architecture for highly available Rancher deployments can be found in our Best Practices Guide.

    Prerequisites

    Node Requirements​

    RancherD must be launched on a Linux OS. At this time, only OSes that leverage systemd are supported.

    The Linux node needs to fulfill the installation requirements for hardware and networking. Docker is not required for RancherD installs.

    To install RancherD on SELinux Enforcing CentOS 8 nodes or RHEL 8 nodes, some additional steps are required.

    Root Access​

    Before running the installation commands, you will need to log in as root:

    sudo -s

    Fixed Registration Address​

    A fixed registration address is recommended for single-node installs and required for high-availability installs with RancherD.

    The fixed registration address is an endpoint that is used for two purposes:

    • To access the Kubernetes API. So you can, for example, modify your kubeconfig file to point to it instead of a specific node.
    • To add new nodes to the Kubernetes cluster. To add nodes to the cluster later, you will run a command on the node that will specify the fixed registration address of the cluster.

    If you are installing Rancher on a single node, the fixed registration address makes it possible to add more nodes to the cluster so that you can convert the single-node install to a high-availability install without causing downtime to the cluster. If you don't set up this address when installing the single-node Kubernetes cluster, you would need to re-run the installation script with a fixed registration address in order to add new nodes to the cluster.

    The fixed registration can be the IP or hostname of any of the server nodes, but in many cases those may change over time as nodes are created and destroyed. Therefore, you should have a stable endpoint in front of the server nodes.

    This endpoint can be set up using any number of approaches, such as:

    • A layer 4 (TCP) load balancer
    • Round-robin DNS
    • Virtual or elastic IP addresses

    The following should be taken into consideration when configuring the load balancer or other endpoint:

    • The RancherD server process listens on port 9345 for new nodes to register.
    • The Kubernetes API is served on port 6443, as normal.
    • In RancherD installs, the Rancher UI is served on port 8443 by default. (This is different from Helm chart installs, where port 443 is used by default.)

    Part I: Installing Rancher

    1. Set up Configurations​

    To avoid certificate errors with the fixed registration address, you should launch the server with the tls-san parameter set. This parameter should refer to your fixed registration address.

    This option adds an additional hostname or IP as a Subject Alternative Name in the server's TLS cert, and it can be specified as a list if you would like to access the Kubernetes cluster via both the IP and the hostname.

    Create the RancherD config file at /etc/rancher/rke2/config.yaml:

    token: my-shared-secret
    tls-san:
      - my-fixed-registration-address.com
      - another-kubernetes-domain.com

    The first server node establishes the secret token that other nodes would register with if they are added to the cluster.

    If you do not specify a pre-shared secret, RancherD will generate one and place it at /var/lib/rancher/rke2/server/node-token.

    To specify your own pre-shared secret as the token, set the token argument on startup.

    Installing Rancher this way will use Rancher-generated certificates. To use your own self-signed or trusted certificates, refer to the configuration guide.

    For information on customizing the RancherD Helm chart values.yaml, refer to this section.

    2. Launch the first server node​

    Run the RancherD installer:

    curl -sfL https://get.rancher.io | sh -

    The RancherD version can be specified using the INSTALL_RANCHERD_VERSION environment variable:

    curl -sfL https://get.rancher.io | INSTALL_RANCHERD_VERSION=v2.5.4-rc6 sh -

    Once installed, the rancherd binary will be on your PATH. You can check out its help text like this:

    rancherd --help
    NAME:
       rancherd - Rancher Kubernetes Engine 2
    ...

    Next, launch RancherD:

    systemctl enable rancherd-server.service
    systemctl start rancherd-server.service

    When RancherD launches, it installs an RKE2 Kubernetes cluster. Use the following command to see the logs of the Kubernetes cluster as it comes up:

    journalctl -eu rancherd-server -f

    3. Set up the kubeconfig file with kubectl​

    Once the Kubernetes cluster is up, set up RancherD’s kubeconfig file and kubectl:

    export KUBECONFIG=/etc/rancher/rke2/rke2.yaml PATH=$PATH:/var/lib/rancher/rke2/bin

    4. Verify that Rancher is installed on the Kubernetes cluster​

    Now, you can start issuing kubectl commands. Use the following commands to verify that Rancher is deployed as a daemonset on the cluster:

    kubectl get daemonset rancher -n cattle-system
    kubectl get pod -n cattle-system

    If you watch the pods, you will see the following pods installed:

    • helm-operation pods in the cattle-system namespace
    • a rancher pod and rancher-webhook pod in the cattle-system namespace
    • a fleet-agent, fleet-controller, and gitjob pod in the fleet-system namespace
    • a rancher-operator pod in the rancher-operator-system namespace

    5. Set the initial Rancher password​

    Once the rancher pod is up and running, run the following:

    rancherd reset-admin

    This will give you the URL, username and password needed to log into Rancher. Follow that URL, plug in the credentials, and you’re up and running with Rancher!

    If Rancher will only manage the local Kubernetes cluster, the installation is complete.

    Part II: High Availability

    If you plan to use the Rancher server to manage downstream Kubernetes clusters, Rancher needs to be highly available. In these steps, you will add more nodes to achieve a high-availability cluster. Since Rancher is running as a daemonset, it will automatically launch on the nodes you add.

    An odd number of nodes is required because the etcd cluster, which contains the cluster data, needs a majority of live nodes to avoid losing quorum. A loss of quorum could require the cluster to be restored from backup. Therefore, we recommend using three nodes.

    When following these steps, you should still be logged in as root.

    1. Configure the fixed registration address on a new node​

    Additional server nodes are launched much like the first, except that you must specify the server and token parameters so that they can successfully connect to the initial server node.

    Here is an example of what the RancherD config file would look like for additional server nodes. By default, this config file is expected to be located at /etc/rancher/rke2/config.yaml.

    server: https://my-fixed-registration-address.com:9345
    token: my-shared-secret
    tls-san:
      - my-fixed-registration-address.com
      - another-kubernetes-domain.com

    2. Launch an additional server node​

    Run the installer on the new node:

    curl -sfL https://get.rancher.io | sh -

    This will download RancherD and install it as a systemd unit on your host.

    Next, launch RancherD:

    systemctl enable rancherd-server.service
    systemctl start rancherd-server.service

    3. Repeat​

    Repeat steps one and two for another Linux node, bringing the number of nodes in the cluster to three.

    Result: Rancher is highly available and the installation is complete.

    Upgrades

    For information on upgrades and rollbacks, refer to this page.

    Configuration

    For information on how to configure certificates, node taints, Rancher Helm chart options, or RancherD CLI options, refer to the configuration reference.

    Uninstall

    To uninstall RancherD from your system, run the command below. This will shut down the process, remove the RancherD binary, and clean up files used by RancherD.

    rancherd-uninstall.sh

    RKE2 Documentation

    For more information on RKE2, the Kubernetes distribution used to provision the underlying cluster, refer to the documentation here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html b/v2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html index 6eef70218c5..5e4b1b0b997 100644 --- a/v2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html +++ b/v2.5/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.html @@ -5,13 +5,13 @@ Install/Upgrade Rancher on a Kubernetes Cluster | Rancher Manager - +
    Version: v2.5

    Install/Upgrade Rancher on a Kubernetes Cluster

    In this section, you'll learn how to deploy Rancher on a Kubernetes cluster using the Helm CLI.

    Prerequisites

    Kubernetes Cluster​

    Set up the Rancher server's local Kubernetes cluster.

    Rancher can be installed on any Kubernetes cluster. This cluster can use upstream Kubernetes, or it can use one of Rancher's Kubernetes distributions, or it can be a managed Kubernetes cluster from a provider such as Amazon EKS.

    For help setting up a Kubernetes cluster, we provide these tutorials:

    • RKE: For the tutorial to install an RKE Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE cluster, refer to this page.
    • K3s: For the tutorial to install a K3s Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability K3s cluster, refer to this page.
    • RKE2: For the tutorial to install an RKE2 Kubernetes cluster, refer to this page. For help setting up the infrastructure for a high-availability RKE2 cluster, refer to this page.
    • Amazon EKS: For details on how to install Rancher on Amazon EKS, including how to install an ingress so that the Rancher server can be accessed, refer to this page.
    • AKS: For details on how to install Rancher with Azure Kubernetes Service, including how to install an ingress so that the Rancher server can be accessed, refer to this page.
    • GKE: For details on how to install Rancher with Google Kubernetes Engine, including how to install an ingress so that the Rancher server can be accessed, refer to this page.

    CLI Tools​

    The following CLI tools are required for setting up the Kubernetes cluster. Please make sure these tools are installed and available in your $PATH.

    Ingress Controller (For Hosted Kubernetes)​

    To deploy Rancher v2.5 on a hosted Kubernetes cluster such as EKS, GKE, or AKS, you should deploy a compatible Ingress controller first to configure SSL termination on Rancher.

    For an example of how to deploy an ingress on EKS, refer to this section.

    Install the Rancher Helm Chart

    Rancher is installed using the Helm package manager for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents.

    With Helm, we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

    For systems without direct internet access, see Air Gap: Kubernetes install.

    To choose a Rancher version to install, refer to Choosing a Rancher Version.

    To choose a version of Helm to install Rancher with, refer to the Helm version requirements

    Note: The installation instructions assume you are using Helm 3. For migration of installs started with Helm 2, refer to the official Helm 2 to 3 migration docs. This section provides a copy of the older installation instructions for Rancher installed on an RKE Kubernetes cluster with Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.

    To set up Rancher,

    1. Add the Helm chart repository
    2. Create a namespace for Rancher
    3. Choose your SSL configuration
    4. Install cert-manager (unless you are bringing your own certificates, or TLS will be terminated on a load balancer)
    5. Install Rancher with Helm and your chosen certificate option
    6. Verify that the Rancher server is successfully deployed
    7. Save your options

    1. Add the Helm Chart Repository​

    Use helm repo add command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see Choosing a Version of Rancher.

    • Latest: Recommended for trying out the newest features
      helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
    • Stable: Recommended for production environments
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
    • Alpha: Experimental preview of upcoming releases.
      helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
      Note: Upgrades are not supported to, from, or between Alphas.

    2. Create a Namespace for Rancher​

    We'll need to define a Kubernetes namespace where the resources created by the Chart should be installed. This should always be cattle-system:

    kubectl create namespace cattle-system

    3. Choose your SSL Configuration​

    The Rancher management server is designed to be secure by default and requires SSL/TLS configuration.

    Note: If you want terminate SSL/TLS externally, see TLS termination on an External Load Balancer.

    There are three recommended options for the source of the certificate used for TLS termination at the Rancher server:

    • Rancher-generated TLS certificate: In this case, you will need to install cert-manager into the cluster. Rancher utilizes cert-manager to issue and maintain its certificates. Rancher will generate a CA certificate of its own, and sign a cert using that CA. cert-manager is then responsible for managing that certificate.
    • Let's Encrypt: The Let's Encrypt option also uses cert-manager. However, in this case, cert-manager is combined with a special Issuer for Let's Encrypt that performs all actions (including request and validation) necessary for getting a Let's Encrypt issued cert. This configuration uses HTTP validation (HTTP-01), so the load balancer must have a public DNS record and be accessible from the internet.
    • Bring your own certificate: This option allows you to bring your own public- or private-CA signed certificate. Rancher will use that certificate to secure websocket and HTTPS traffic. In this case, you must upload this certificate (and associated key) as PEM-encoded files with the name tls.crt and tls.key. If you are using a private CA, you must also upload that certificate. This is due to the fact that this private CA may not be trusted by your nodes. Rancher will take that CA certificate, and generate a checksum from it, which the various Rancher components will use to validate their connection to Rancher.
    ConfigurationHelm Chart OptionRequires cert-manager
    Rancher Generated Certificates (Default)ingress.tls.source=rancheryes
    Let’s Encryptingress.tls.source=letsEncryptyes
    Certificates from Filesingress.tls.source=secretno

    4. Install cert-manager​

    You should skip this step if you are bringing your own certificate files (option ingress.tls.source=secret), or if you use TLS termination on an external load balancer.

    This step is only required to use certificates issued by Rancher's generated CA (ingress.tls.source=rancher) or to request Let's Encrypt issued certificates (ingress.tls.source=letsEncrypt).

    Click to Expand

    Important: Recent changes to cert-manager require an upgrade. If you are upgrading Rancher and using a version of cert-manager older than v0.11.0, please see our upgrade documentation.

    These instructions are adapted from the official cert-manager documentation.

    # If you have installed the CRDs manually instead of with the `--set installCRDs=true` option added to your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart:
    kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.1/cert-manager.crds.yaml

    # Add the Jetstack Helm repository
    helm repo add jetstack https://charts.jetstack.io

    # Update your local Helm chart repository cache
    helm repo update

    # Install the cert-manager Helm chart
    helm install cert-manager jetstack/cert-manager \
      --namespace cert-manager \
      --create-namespace \
      --version v1.5.1

    Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:

    kubectl get pods --namespace cert-manager

    NAME                                       READY   STATUS    RESTARTS   AGE
    cert-manager-5c6866597-zw7kh               1/1     Running   0          2m
    cert-manager-cainjector-577f6d9fd7-tr77l   1/1     Running   0          2m
    cert-manager-webhook-787858fcdb-nlzsq      1/1     Running   0          2m

    5. Install Rancher with Helm and Your Chosen Certificate Option​

    The exact command to install Rancher differs depending on the certificate configuration.

    However, irrespective of the certificate configuration, the name of the Rancher installation in the cattle-system namespace should always be rancher.

    The default is for Rancher to generate a self-signed CA, and uses cert-manager to issue the certificate for access to the Rancher server interface.

    Because rancher is the default option for ingress.tls.source, we are not specifying ingress.tls.source when running the helm install command.

    • Set hostname to the DNS record that resolves to your load balancer.
    • Set replicas to the number of replicas to use for the Rancher Deployment. This defaults to 3; if you have less than 3 nodes in your cluster you should reduce it accordingly.
    • To install a specific Rancher version, use the --version flag, example: --version 2.3.6.
    • If you are installing an alpha version, Helm requires adding the --devel option to the command.
    helm install rancher rancher-<CHART_REPO>/rancher \
      --namespace cattle-system \
      --set hostname=rancher.my.org \
      --set replicas=3

    Wait for Rancher to be rolled out:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    The Rancher chart configuration has many options for customizing the installation to suit your specific environment. Here are some common advanced scenarios.

    See the Chart Options for the full list of options.

    6. Verify that the Rancher Server is Successfully Deployed​

    After adding the secrets, check if Rancher was rolled out successfully:

    kubectl -n cattle-system rollout status deploy/rancher
    Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available...
    deployment "rancher" successfully rolled out

    If you see the following error: error: deployment "rancher" exceeded its progress deadline, you can check the status of the deployment by running the following command:

    kubectl -n cattle-system get deploy rancher
    NAME      DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
    rancher   3         3         3            3           3m

    It should show the same count for DESIRED and AVAILABLE.

    7. Save Your Options​

    Make sure you save the --set options you used. You will need to use the same options when you upgrade Rancher to new versions with Helm.

    Finishing Up​

    That's it. You should have a functional Rancher server.

    In a web browser, go to the DNS name that forwards traffic to your load balancer. Then you should be greeted by the colorful login page.

    Doesn't work? Take a look at the Troubleshooting Page

    Optional Next Steps​

    Enable the Enterprise Cluster Manager.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/installation-and-upgrade.html b/v2.5/pages-for-subheaders/installation-and-upgrade.html index 485833f7485..ebf0ac93bac 100644 --- a/v2.5/pages-for-subheaders/installation-and-upgrade.html +++ b/v2.5/pages-for-subheaders/installation-and-upgrade.html @@ -5,13 +5,13 @@ Installing/Upgrading Rancher | Rancher Manager - +
    Version: v2.5

    Installing/Upgrading Rancher

    This section provides an overview of the architecture options of installing Rancher, describing advantages of each option.

    Terminology

    In this section,

    • The Rancher server manages and provisions Kubernetes clusters. You can interact with downstream Kubernetes clusters through the Rancher server's user interface.
    • RKE (Rancher Kubernetes Engine) is a certified Kubernetes distribution and CLI/library which creates and manages a Kubernetes cluster.
    • K3s (Lightweight Kubernetes) is also a fully compliant Kubernetes distribution. It is newer than RKE, easier to use, and more lightweight, with a binary size of less than 100 MB.
    • RKE2 is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.
    • RancherD was an experimental tool for installing Rancher; a single binary that first launched an RKE2 Kubernetes cluster, then installed the Rancher server Helm chart on the cluster. It was available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    Changes to Installation in Rancher v2.5

    In Rancher v2.5, the Rancher management server can be installed on any Kubernetes cluster, including hosted clusters, such as Amazon EKS clusters.

    For Docker installations, a local Kubernetes cluster is installed in the single Docker container, and Rancher is installed on the local cluster.

    The restrictedAdmin Helm chart option was added. When this option is set to true, the initial Rancher user has restricted access to the local Kubernetes cluster to prevent privilege escalation. For more information, see the section about the restricted-admin role.

    Overview of Installation Options

    Rancher can be installed on these main architectures:

    High-availability Kubernetes Install with the Helm CLI​

    We recommend using Helm, a Kubernetes package manager, to install Rancher on multiple nodes on a dedicated Kubernetes cluster. For RKE clusters, three nodes are required to achieve a high-availability cluster. For K3s clusters, only two nodes are required.

    High-availability Kubernetes Install with RancherD​

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    RancherD is a single binary that first launches an RKE2 Kubernetes cluster, then installs the Rancher server Helm chart on the cluster.

    In both the RancherD install and the Helm CLI install, Rancher is installed as a Helm chart on a Kubernetes cluster.

    Configuration and upgrading are also simplified with RancherD. When you upgrade the RancherD binary, both the Kubernetes cluster and the Rancher Helm chart are upgraded.

    Automated Quickstart to Deploy Rancher on Amazon EKS​

    Rancher and Amazon Web Services collaborated on a quick start guide for deploying Rancher on an EKS Kubernetes cluster following AWS best practices. The deployment guide is here.

    Single-node Kubernetes Install​

    Rancher can be installed on a single-node Kubernetes cluster. In this case, the Rancher server doesn't have high availability, which is important for running Rancher in production.

    However, this option is useful if you want to save resources by using a single node in the short term, while preserving a high-availability migration path. In the future, you can add nodes to the cluster to get a high-availability Rancher server.

    Docker Install​

    For test and demonstration purposes, Rancher can be installed with Docker on a single node.

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Other Options​

    There are also separate instructions for installing Rancher in an air gap environment or behind an HTTP proxy:

    Level of Internet AccessKubernetes Installation - Strongly RecommendedDocker Installation
    With direct access to the InternetDocsDocs
    Behind an HTTP proxyDocsThese docs, plus this configuration
    In an air gap environmentDocsDocs

    We recommend installing Rancher on a Kubernetes cluster, because in a multi-node cluster, the Rancher management server becomes highly available. This high-availability configuration helps maintain consistent access to the downstream Kubernetes clusters that Rancher will manage.

    For that reason, we recommend that for a production-grade architecture, you should set up a high-availability Kubernetes cluster, then install Rancher on it. After Rancher is installed, you can use Rancher to deploy and manage Kubernetes clusters.

    For testing or demonstration purposes, you can install Rancher in single Docker container. In this Docker install, you can use Rancher to set up Kubernetes clusters out-of-the-box. The Docker install allows you to explore the Rancher server functionality, but it is intended to be used for development and testing purposes only.

    Our instructions for installing Rancher on Kubernetes describe how to first use K3s or RKE to create and manage a Kubernetes cluster, then install Rancher onto that cluster.

    When the nodes in your Kubernetes cluster are running and fulfill the node requirements, you will use Helm to deploy Rancher onto Kubernetes. Helm uses Rancher's Helm chart to install a replica of Rancher on each node in the Kubernetes cluster. We recommend using a load balancer to direct traffic to each replica of Rancher in the cluster.

    For a longer discussion of Rancher architecture, refer to the architecture overview, recommendations for production-grade architecture, or our best practices guide.

    Prerequisites

    Before installing Rancher, make sure that your nodes fulfill all of the installation requirements.

    Architecture Tip

    For the best performance and greater security, we recommend a separate, dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    For more architecture recommendations, refer to this page.

    More Options for Installations on a Kubernetes Cluster​

    Refer to the Helm chart options for details on installing Rancher on a Kubernetes cluster with other configurations, including:

    In the Rancher installation instructions, we recommend using K3s or RKE to set up a Kubernetes cluster before installing Rancher on the cluster. Both K3s and RKE have many configuration options for customizing the Kubernetes cluster to suit your specific environment. For the full list of their capabilities, refer to their documentation:

    More Options for Installations with Docker​

    Refer to the docs about options for Docker installs for details about other configurations including:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/installation-references.html b/v2.5/pages-for-subheaders/installation-references.html index 0845e1bbdd8..dfa9bf81907 100644 --- a/v2.5/pages-for-subheaders/installation-references.html +++ b/v2.5/pages-for-subheaders/installation-references.html @@ -5,13 +5,13 @@ Installation References | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/installation-requirements.html b/v2.5/pages-for-subheaders/installation-requirements.html index 614df5b1a98..d20c41a4d22 100644 --- a/v2.5/pages-for-subheaders/installation-requirements.html +++ b/v2.5/pages-for-subheaders/installation-requirements.html @@ -5,13 +5,13 @@ Installation Requirements | Rancher Manager - +
    Version: v2.5

    Installation Requirements

    This page describes the software, hardware, and networking requirements for the nodes where the Rancher server will be installed. The Rancher server can be installed on a single node or a high-availability Kubernetes cluster.

    It is important to note that if you install Rancher on a Kubernetes cluster, requirements are different from the node requirements for downstream user clusters, which will run your apps and services.

    Make sure the node(s) for the Rancher server fulfill the following requirements:

    For a list of best practices that we recommend for running the Rancher server in production, refer to the best practices section.

    The Rancher UI works best in Firefox or Chrome.

    Operating Systems and Container Runtime Requirements

    Rancher should work with any modern Linux distribution.

    Docker is required for nodes that will run RKE Kubernetes clusters. It is not required for RancherD or RKE2 Kubernetes installs.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms.

    For details on which OS and Docker versions were tested with each Rancher version, refer to the support maintenance terms.

    All supported operating systems are 64-bit x86.

    The ntp (Network Time Protocol) package should be installed. This prevents errors with certificate validation that can occur when the time is not synchronized between the client and server.

    Some distributions of Linux may have default firewall rules that block communication with Helm. We recommend disabling firewalld. For Kubernetes 1.19 and 1.20, firewalld must be turned off.

    If you don't feel comfortable doing so you might check suggestions in the respective issue. Some users were successful creating a separate firewalld zone with a policy of ACCEPT for the Pod CIDR.

    If you plan to run Rancher on ARM64, see Running on ARM64 (Experimental).

    RKE Specific Requirements​

    For the container runtime, RKE should work with any modern Docker version.

    Note that the following sysctl setting must be applied:

    net.bridge.bridge-nf-call-iptables=1

    K3s Specific Requirements​

    For the container runtime, K3s should work with any modern version of Docker or containerd.

    Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms. To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

    If you are installing Rancher on a K3s cluster with Raspbian Buster, follow these steps to switch to legacy iptables.

    If you are installing Rancher on a K3s cluster with Alpine Linux, follow these steps for additional setup.

    RancherD Specific Requirements​

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    At this time, only Linux OSes that leverage systemd are supported.

    To install RancherD on SELinux Enforcing CentOS 8 or RHEL 8 nodes, some additional steps are required.

    Docker is not required for RancherD installs.

    RKE2 Specific Requirements​

    The RKE2 install is available as of v2.5.6.

    For details on which OS versions were tested with RKE2, refer to the support maintenance terms.

    Docker is not required for RKE2 installs.

    The Ingress should be deployed as DaemonSet to ensure your load balancer can successfully route traffic to all nodes. Currently, RKE2 deploys nginx-ingress as a deployment by default, so you will need to deploy it as a DaemonSet by following these steps.

    Installing Docker​

    Docker is required for Helm chart installs, and it can be installed by following the steps in the official Docker documentation. Rancher also provides scripts to install Docker with one command.

    Docker is not required for RancherD installs.

    Hardware Requirements

    The following sections describe the CPU, memory, and disk requirements for the nodes where the Rancher server is installed.

    CPU and Memory

    Hardware requirements scale based on the size of your Rancher deployment. Provision each individual node according to the requirements. The requirements are different depending on if you are installing Rancher in a single container with Docker, or if you are installing Rancher on a Kubernetes cluster.

    RKE and Hosted Kubernetes​

    These CPU and memory requirements apply to each host in the Kubernetes cluster where the Rancher server is installed.

    These requirements apply to RKE Kubernetes clusters, as well as to hosted Kubernetes clusters such as EKS.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 150Up to 150028 GB
    MediumUp to 300Up to 3000416 GB
    LargeUp to 500Up to 5000832 GB
    X-LargeUp to 1000Up to 10,0001664 GB
    XX-LargeUp to 2000Up to 20,00032128 GB

    Every use case and environment is different. Please contact Rancher to review yours.

    K3s Kubernetes​

    These CPU and memory requirements apply to each host in a K3s Kubernetes cluster where the Rancher server is installed.

    Deployment SizeClustersNodesvCPUsRAMDatabase Size
    SmallUp to 150Up to 150028 GB2 cores, 4 GB + 1000 IOPS
    MediumUp to 300Up to 3000416 GB2 cores, 4 GB + 1000 IOPS
    LargeUp to 500Up to 5000832 GB2 cores, 4 GB + 1000 IOPS
    X-LargeUp to 1000Up to 10,0001664 GB2 cores, 4 GB + 1000 IOPS
    XX-LargeUp to 2000Up to 20,00032128 GB2 cores, 4 GB + 1000 IOPS

    Every use case and environment is different. Please contact Rancher to review yours.

    RancherD​

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    These CPU and memory requirements apply to each instance with RancherD installed. Minimum recommendations are outlined here.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 5Up to 5025 GB
    MediumUp to 15Up to 20039 GB

    RKE2 Kubernetes​

    These CPU and memory requirements apply to each instance with RKE2 installed. Minimum recommendations are outlined here.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 5Up to 5025 GB
    MediumUp to 15Up to 20039 GB

    Docker​

    These CPU and memory requirements apply to a host with a single-node installation of Rancher.

    Deployment SizeClustersNodesvCPUsRAM
    SmallUp to 5Up to 5014 GB
    MediumUp to 15Up to 20028 GB

    Ingress

    Each node in the Kubernetes cluster that Rancher is installed on should run an Ingress.

    The Ingress should be deployed as DaemonSet to ensure your load balancer can successfully route traffic to all nodes.

    For RKE, K3s and RancherD installations, you don't have to install the Ingress manually because it is installed by default.

    For hosted Kubernetes clusters (EKS, GKE, AKS) and RKE2 Kubernetes installations, you will need to set up the ingress.

    Ingress for RKE2​

    Currently, RKE2 deploys nginx-ingress as a deployment by default, so you will need to deploy it as a DaemonSet by following these steps.

    Ingress for EKS​

    For an example of how to deploy an nginx-ingress-controller with a LoadBalancer service, refer to this section.

    Disks

    Rancher performance depends on etcd in the cluster performance. To ensure optimal speed, we recommend always using SSD disks to back your Rancher management Kubernetes cluster. On cloud providers, you will also want to use the minimum size that allows the maximum IOPS. In larger clusters, consider using dedicated storage devices for etcd data and wal directories.

    Networking Requirements

    This section describes the networking requirements for the node(s) where the Rancher server is installed.

    Node IP Addresses​

    Each node used should have a static IP configured, regardless of whether you are installing Rancher on a single node or on an HA cluster. In case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    Port Requirements​

    To operate properly, Rancher requires a number of ports to be open on Rancher nodes and on downstream Kubernetes cluster nodes. Port Requirements lists all the necessary ports for Rancher and Downstream Clusters for the different cluster types.

    RancherD on SELinux Enforcing CentOS 8 or RHEL 8 Nodes

    Before installing Rancher on SELinux Enforcing CentOS 8 nodes or RHEL 8 nodes, you must install container-selinux and iptables:

    sudo yum install iptables
    sudo yum install container-selinux
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/integrations-in-rancher.html b/v2.5/pages-for-subheaders/integrations-in-rancher.html index 7feb2f0535d..1dd4e766345 100644 --- a/v2.5/pages-for-subheaders/integrations-in-rancher.html +++ b/v2.5/pages-for-subheaders/integrations-in-rancher.html @@ -5,13 +5,13 @@ Integrations in Rancher | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/introduction.html b/v2.5/pages-for-subheaders/introduction.html index 6ab851db3c5..46572420a29 100644 --- a/v2.5/pages-for-subheaders/introduction.html +++ b/v2.5/pages-for-subheaders/introduction.html @@ -5,13 +5,13 @@ Introduction | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/istio-setup-guide.html b/v2.5/pages-for-subheaders/istio-setup-guide.html index f1bae5b2372..04654356bdc 100644 --- a/v2.5/pages-for-subheaders/istio-setup-guide.html +++ b/v2.5/pages-for-subheaders/istio-setup-guide.html @@ -5,13 +5,13 @@ Setup Guide | Rancher Manager - +
    Version: v2.5

    Setup Guide

    This section describes how to enable Istio and start using it in your projects.

    If you use Istio for traffic management, you will need to allow external traffic to the cluster. In that case, you will need to follow all of the steps below.

    Prerequisites

    This guide assumes you have already installed Rancher, and you have already provisioned a separate Kubernetes cluster on which you will install Istio.

    The nodes in your cluster must meet the CPU and memory requirements.

    The workloads and services that you want to be controlled by Istio must meet Istio's requirements.

    Install

    Quick Setup If you don't need external traffic to reach Istio, and you just want to set up Istio for monitoring and tracing traffic within the cluster, skip the steps for setting up the Istio gateway and setting up Istio's components for traffic management.

    1. Enable Istio in the cluster.
    2. Enable Istio in all the namespaces where you want to use it.
    3. Add deployments and services that have the Istio sidecar injected.
    4. Set up the Istio gateway.
    5. Set up Istio's components for traffic management.
    6. Generate traffic and see Istio in action.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/istio.html b/v2.5/pages-for-subheaders/istio.html index 7fb85c5a223..cc059727177 100644 --- a/v2.5/pages-for-subheaders/istio.html +++ b/v2.5/pages-for-subheaders/istio.html @@ -5,13 +5,13 @@ Istio | Rancher Manager - +
    Version: v2.5

    Istio

    Istio is an open-source tool that makes it easier for DevOps teams to observe, secure, control, and troubleshoot the traffic within a complex network of microservices.

    As a network of microservices changes and grows, the interactions between them can become increasingly difficult to manage and understand. In such a situation, it is useful to have a service mesh as a separate infrastructure layer. Istio's service mesh lets you manipulate traffic between microservices without changing the microservices directly.

    Our integration of Istio is designed so that a Rancher operator, such as an administrator or cluster owner, can deliver Istio to a team of developers. Then developers can use Istio to enforce security policies, troubleshoot problems, or manage traffic for green/blue deployments, canary deployments, or A/B testing.

    This core service mesh provides features that include but are not limited to the following:

    • Traffic Management such as ingress and egress routing, circuit breaking, mirroring.
    • Security with resources to authenticate and authorize traffic and users, mTLS included.
    • Observability of logs, metrics, and distributed traffic flows.

    After setting up istio you can leverage Istio's control plane functionality through the Cluster Explorer, kubectl, or istioctl.

    Istio needs to be set up by a cluster-admin before it can be used in a project.

    What's New in Rancher v2.5​

    The overall architecture of Istio has been simplified. A single component, Istiod, has been created by combining Pilot, Citadel, Galley and the sidecar injector. Node Agent functionality has also been merged into istio-agent.

    Addons that were previously installed by Istio (cert-manager, Grafana, Jaeger, Kiali, Prometheus, Zipkin) will now need to be installed separately. Istio will support installation of integrations that are from the Istio Project and will maintain compatibility with those that are not.

    A Prometheus integration will still be available through an installation of Rancher Monitoring, or by installing your own Prometheus operator. Rancher's Istio chart will also install Kiali by default to ensure you can get a full picture of your microservices out of the box.

    Istio has migrated away from Helm as a way to install Istio and now provides installation through the istioctl binary or Istio Operator. To ensure the easiest interaction with Istio, Rancher's Istio will maintain a Helm chart that utilizes the istioctl binary to manage your Istio installation.

    This Helm chart will be available via the Apps and Marketplace in the UI. A user that has access to the Rancher Chart's catalog will need to set up Istio before it can be used in the project.

    Tools Bundled with Istio​

    Our Istio installer wraps the istioctl binary commands in a handy Helm chart, including an overlay file option to allow complex customization.

    It also includes the following:

    Kiali​

    Kiali is a comprehensive visualization aid used for graphing traffic flow throughout the service mesh. It allows you to see how they are connected, including the traffic rates and latencies between them.

    You can check the health of the service mesh, or drill down to see the incoming and outgoing requests to a single component.

    Jaeger​

    Bundled as of v2.5.4

    Our Istio installer includes a quick-start, all-in-one installation of Jaeger, a tool used for tracing distributed systems.

    Note that this is not a production-qualified deployment of Jaeger. This deployment uses an in-memory storage component, while a persistent storage component is recommended for production. For more information on which deployment strategy you may need, refer to the Jaeger documentation.

    Prerequisites​

    Before enabling Istio, we recommend that you confirm that your Rancher worker nodes have enough CPU and memory to run all of the components of Istio.

    If you are installing Istio on RKE2 cluster, some additional steps are required. For details, see this section.

    Setup Guide​

    Refer to the setup guide for instructions on how to set up Istio and use it in a project.

    Remove Istio​

    To remove Istio components from a cluster, namespace, or workload, refer to the section on uninstalling Istio.

    Migrate From Previous Istio Version​

    There is no upgrade path for Istio versions less than 1.7.x. To successfully install Istio in the Cluster Explorer, you will need to disable your existing Istio in the Cluster Manager.

    If you have a significant amount of additional Istio CRDs you might consider manually migrating CRDs that are supported in both versions of Istio. You can do this by running kubectl get <resource> -n istio-system -o yaml, save the output yaml and re-apply in the new version.

    Another option is to manually uninstall istio resources one at a time, but leave the resources that are supported in both versions of Istio and that will not be installed by the newest version. This method is more likely to result in issues installing the new version, but could be a good option depending on your situation.

    Accessing Visualizations​

    By default, only cluster-admins have access to Kiali. For instructions on how to allow admin, edit or views roles to access them, see this section.

    After Istio is set up in a cluster, Grafana, Prometheus,and Kiali are available in the Rancher UI.

    To access the Grafana and Prometheus visualizations, from the Cluster Explorer navigate to the Monitoring app overview page, and click on Grafana or Prometheus

    To access the Kiali visualization, from the Cluster Explorer navigate to the Istio app overview page, and click on Kiali. From here you can access the Traffic Graph tab or the Traffic Metrics tab to see network visualizations and metrics.

    By default, all namespace will picked up by prometheus and make data available for Kiali graphs. Refer to selector/scrape config setup if you would like to use a different configuration for prometheus data scraping.

    Your access to the visualizations depend on your role. Grafana and Prometheus are only available for cluster-admin roles. The Kiali UI is available only to cluster-admin by default, but cluster-admin can allow other roles to access them by editing the Istio values.yaml.

    Architecture​

    Istio installs a service mesh that uses Envoy sidecar proxies to intercept traffic to each workload. These sidecars intercept and manage service-to-service communication, allowing fine-grained observation and control over traffic within the cluster.

    Only workloads that have the Istio sidecar injected can be tracked and controlled by Istio.

    When a namespace has Istio enabled, new workloads deployed in the namespace will automatically have the Istio sidecar. You need to manually enable Istio in preexisting workloads.

    For more information on the Istio sidecar, refer to the Istio sidecare-injection docs and for more information on Istio's architecture, refer to the Istio Architecture docs

    Multiple Ingresses​

    By default, each Rancher-provisioned cluster has one NGINX ingress controller allowing traffic into the cluster. Istio also installs an ingress gateway by default into the istio-system namespace. The result is that your cluster will have two ingresses in your cluster.

    In an Istio-enabled cluster, you can have two ingresses: the default Nginx ingress, and the default Istio controller.

    Additional Istio Ingress gateways can be enabled via the overlay file.

    Egress Support​

    By default the Egress gateway is disabled, but can be enabled on install or upgrade through the values.yaml or via the overlay file.

    Additional Steps for Installing Istio on an RKE2 Cluster​

    To install Istio on an RKE2 cluster, follow the steps in this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/kubernetes-cluster-setup.html b/v2.5/pages-for-subheaders/kubernetes-cluster-setup.html index c4e30750b0c..80d6068306d 100644 --- a/v2.5/pages-for-subheaders/kubernetes-cluster-setup.html +++ b/v2.5/pages-for-subheaders/kubernetes-cluster-setup.html @@ -5,13 +5,13 @@ Don't have a Kubernetes cluster? Try one of these tutorials. | Rancher Manager - +
    Version: v2.5

    Don't have a Kubernetes cluster? Try one of these tutorials.

    This section contains information on how to install a Kubernetes cluster that the Rancher server can be installed on.

    In Rancher v2.5, Rancher can run on any Kubernetes cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html b/v2.5/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html index 0ae90a7cc59..43bc7602d74 100644 --- a/v2.5/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html +++ b/v2.5/pages-for-subheaders/kubernetes-clusters-in-rancher-setup.html @@ -5,13 +5,13 @@ Setting up Kubernetes Clusters in Rancher | Rancher Manager - +
    Version: v2.5

    Setting up Kubernetes Clusters in Rancher

    Rancher simplifies the creation of clusters by allowing you to create them through the Rancher UI rather than more complex alternatives. Rancher provides multiple options for launching a cluster. Use the option that best fits your use case.

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    For a conceptual overview of how the Rancher server provisions clusters and what tools it uses to provision them, refer to the architecture page.

    Cluster Management Capabilities by Cluster Type​

    The following table summarizes the options and settings available for each cluster type:

    ActionRancher Launched Kubernetes ClustersEKS and GKE Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓
    Authorized Cluster Endpoint✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Setting up Clusters in a Hosted Kubernetes Provider​

    In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

    For more information, refer to the section on hosted Kubernetes clusters.

    Launching Kubernetes with Rancher​

    Rancher uses the Rancher Kubernetes Engine (RKE) as a library when provisioning Kubernetes on your own nodes. RKE is Rancher’s own lightweight Kubernetes installer.

    In RKE clusters, Rancher manages the deployment of Kubernetes. These clusters can be deployed on any bare metal server, cloud provider, or virtualization platform.

    These nodes can be dynamically provisioned through Rancher's UI, which calls Docker Machine to launch nodes on various cloud providers.

    If you already have a node that you want to add to an RKE cluster, you can add it to the cluster by running a Rancher agent container on it.

    For more information, refer to the section on RKE clusters.

    Launching Kubernetes and Provisioning Nodes in an Infrastructure Provider​

    Rancher can dynamically provision nodes in infrastructure providers such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

    Using Rancher, you can create pools of nodes based on a node template. This template defines the parameters used to launch nodes in your cloud providers.

    One benefit of using nodes hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically replace it, thus maintaining the expected cluster configuration.

    The cloud providers available for creating a node template are decided based on the node drivers active in the Rancher UI.

    For more information, refer to the section on nodes hosted by an infrastructure provider

    Launching Kubernetes on Existing Custom Nodes​

    When setting up this type of cluster, Rancher installs Kubernetes on existing custom nodes, which creates a custom cluster.

    You can bring any nodes you want to Rancher and use them to create a cluster.

    These nodes include on-prem bare metal servers, cloud-hosted virtual machines, or on-prem virtual machines.

    Registering Existing Clusters​

    The cluster registration feature replaces the feature to import clusters.

    Registering EKS clusters now provides additional benefits. For the most part, registered EKS clusters and EKS clusters created in Rancher are treated the same way in the Rancher UI, except for deletion.

    When you delete an EKS cluster that was created in Rancher, the cluster is destroyed. When you delete an EKS cluster that was registered in Rancher, it is disconnected from the Rancher server, but it still exists and you can still access it in the same way you did before it was registered in Rancher.

    For more information, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/kubernetes-components.html b/v2.5/pages-for-subheaders/kubernetes-components.html index f517bf07ac3..ecafb03bb97 100644 --- a/v2.5/pages-for-subheaders/kubernetes-components.html +++ b/v2.5/pages-for-subheaders/kubernetes-components.html @@ -5,13 +5,13 @@ Kubernetes Components | Rancher Manager - +
    Version: v2.5

    Kubernetes Components

    The commands and steps listed in this section apply to the core Kubernetes components on Rancher Launched Kubernetes clusters.

    This section includes troubleshooting tips in the following categories:

    Kubernetes Component Diagram

    Cluster diagram

    Lines show the traffic flow between components. Colors are used purely for visual aid
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/kubernetes-resources-setup.html b/v2.5/pages-for-subheaders/kubernetes-resources-setup.html index ae6db9b2828..634ef3e4b37 100644 --- a/v2.5/pages-for-subheaders/kubernetes-resources-setup.html +++ b/v2.5/pages-for-subheaders/kubernetes-resources-setup.html @@ -5,13 +5,13 @@ Kubernetes Resources | Rancher Manager - +
    Version: v2.5

    Kubernetes Resources

    The Cluster Explorer is a new feature in Rancher v2.5 that allows you to view and manipulate all of the custom resources and CRDs in a Kubernetes cluster from the Rancher UI. This section will be updated to reflect the way that Kubernetes resources are handled in Rancher v2.5.

    Workloads​

    Deploy applications to your cluster nodes using workloads, which are objects that contain pods that run your apps, along with metadata that set rules for the deployment's behavior. Workloads can be deployed within the scope of the entire clusters or within a namespace.

    When deploying a workload, you can deploy from any image. There are a variety of workload types to choose from which determine how your application should run.

    Following a workload deployment, you can continue working with it. You can:

    • Upgrade the workload to a newer version of the application it's running.
    • Roll back a workload to a previous version, if an issue occurs during upgrade.
    • Add a sidecar, which is a workload that supports a primary workload.

    Load Balancing and Ingress​

    Load Balancers​

    After you launch an application, it's only available within the cluster. It can't be reached externally.

    If you want your applications to be externally accessible, you must add a load balancer to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

    Rancher supports two types of load balancers:

    For more information, see load balancers.

    Ingress​

    Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive. You can get around this issue by using an ingress.

    Ingress is a set of rules that act as a load balancer. Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster program the load balancer to direct the request to the correct service based on service subdomains or path rules that you've configured.

    For more information, see Ingress.

    When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.

    Service Discovery​

    After you expose your cluster to external requests using a load balancer and/or ingress, it's only available by IP address. To create a resolveable hostname, you must create a service record, which is a record that maps an IP address, external hostname, DNS record alias, workload(s), or labelled pods to a specific hostname.

    For more information, see Service Discovery.

    Pipelines​

    After your project has been configured to a version control provider, you can add the repositories and start configuring a pipeline for each repository.

    For more information, see Pipelines.

    Applications​

    Besides launching individual components of an application, you can use the Rancher catalog to start launching applications, which are Helm charts.

    For more information, see Applications in a Project.

    Kubernetes Resources​

    Within the context of a Rancher project or namespace, resources are files and data that support operation of your pods. Within Rancher, certificates, registries, and secrets are all considered resources. However, Kubernetes classifies resources as different types of secrets. Therefore, within a single project or namespace, individual resources must have unique names to avoid conflicts. Although resources are primarily used to carry sensitive information, they have other uses as well.

    Resources include:

    • Certificates: Files used to encrypt/decrypt data entering or leaving the cluster.
    • ConfigMaps: Files that store general configuration information, such as a group of config files.
    • Secrets: Files that store sensitive data like passwords, tokens, or keys.
    • Registries: Files that carry credentials used to authenticate with private registries.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/launch-kubernetes-with-rancher.html b/v2.5/pages-for-subheaders/launch-kubernetes-with-rancher.html index 94379bc8124..557b32e04f6 100644 --- a/v2.5/pages-for-subheaders/launch-kubernetes-with-rancher.html +++ b/v2.5/pages-for-subheaders/launch-kubernetes-with-rancher.html @@ -5,13 +5,13 @@ Launching Kubernetes with Rancher | Rancher Manager - +
    Version: v2.5

    Launching Kubernetes with Rancher

    You can have Rancher launch a Kubernetes cluster using any nodes you want. When Rancher deploys Kubernetes onto these nodes, it uses Rancher Kubernetes Engine (RKE), which is Rancher's own lightweight Kubernetes installer. It can launch Kubernetes on any computers, including:

    • Bare-metal servers
    • On-premise virtual machines
    • Virtual machines hosted by an infrastructure provider

    Rancher can install Kubernetes on existing nodes, or it can dynamically provision nodes in an infrastructure provider and install Kubernetes on them.

    RKE clusters include clusters that Rancher launched on Windows nodes or other existing custom nodes, as well as clusters that Rancher launched with new nodes on Azure, Digital Ocean, EC2, or vSphere.

    Requirements​

    If you use RKE to set up a cluster, your nodes must meet the requirements for nodes in downstream user clusters.

    Launching Kubernetes on New Nodes in an Infrastructure Provider​

    Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your cloud providers.

    One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

    For more information, refer to the section on launching Kubernetes on new nodes.

    Launching Kubernetes on Existing Custom Nodes​

    In this scenario, you want to install Kubernetes on bare-metal servers, on-prem virtual machines, or virtual machines that already exist in a cloud provider. With this option, you will run a Rancher agent Docker container on the machine.

    If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

    For more information, refer to the section on custom nodes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/load-balancer-and-ingress-controller.html b/v2.5/pages-for-subheaders/load-balancer-and-ingress-controller.html index 48c993c08eb..9292596b9ae 100644 --- a/v2.5/pages-for-subheaders/load-balancer-and-ingress-controller.html +++ b/v2.5/pages-for-subheaders/load-balancer-and-ingress-controller.html @@ -5,13 +5,13 @@ Set Up Load Balancer and Ingress Controller within Rancher | Rancher Manager - +
    Version: v2.5

    Set Up Load Balancer and Ingress Controller within Rancher

    Within Rancher, you can set up load balancers and ingress controllers to redirect service requests.

    Load Balancers​

    After you launch an application, the app is only available within the cluster. It can't be reached from outside the cluster.

    If you want your applications to be externally accessible, you must add a load balancer or ingress to your cluster. Load balancers create a gateway for external connections to access your cluster, provided that the user knows the load balancer's IP address and the application's port number.

    Rancher supports two types of load balancers:

    For more information, see load balancers.

    Load Balancer Limitations​

    Load Balancers have a couple of limitations you should be aware of:

    • Load Balancers can only handle one IP address per service, which means if you run multiple services in your cluster, you must have a load balancer for each service. Running multiples load balancers can be expensive.

    • If you want to use a load balancer with a Hosted Kubernetes cluster (i.e., clusters hosted in GKE, EKS, or AKS), the load balancer must be running within that cloud provider's infrastructure. Please review the compatibility tables regarding support for load balancers based on how you've provisioned your clusters:

    - [Support for Layer-4 Load Balancing](/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing#support-for-layer-4-load-balancing)

    - [Support for Layer-7 Load Balancing](/v2.5/how-to-guides/new-user-guides/kubernetes-resources-setup/load-balancer-and-ingress-controller/layer-4-and-layer-7-load-balancing#support-for-layer-7-load-balancing)

    Ingress​

    As mentioned in the limitations above, the disadvantages of using a load balancer are:

    • Load Balancers can only handle one IP address per service.
    • If you run multiple services in your cluster, you must have a load balancer for each service.
    • It can be expensive to have a load balancer for every service.

    In contrast, when an ingress is used as the entrypoint into a cluster, the ingress can route traffic to multiple services with greater flexibility. It can map multiple HTTP requests to services without individual IP addresses for each service.

    Therefore, it is useful to have an ingress if you want multiple services to be exposed with the same IP address, the same Layer 7 protocol, or the same privileged node-ports: 80 and 443.

    Ingress works in conjunction with one or more ingress controllers to dynamically route service requests. When the ingress receives a request, the ingress controller(s) in your cluster direct the request to the correct service based on service subdomains or path rules that you've configured.

    Each Kubernetes Ingress resource corresponds roughly to a file in /etc/nginx/sites-available/ containing a server{} configuration block, where requests for specific files and folders are configured.

    Your ingress, which creates a port of entry to your cluster similar to a load balancer, can reside within your cluster or externally. Ingress and ingress controllers residing in RKE-launched clusters are powered by Nginx.

    Ingress can provide other functionality as well, such as SSL termination, name-based virtual hosting, and more.

    Using Rancher in a High Availability Configuration?

    Refrain from adding an Ingress to the local cluster. The Nginx Ingress Controller that Rancher uses acts as a global entry point for all clusters managed by Rancher, including the local cluster. Therefore, when users try to access an application, your Rancher connection may drop due to the Nginx configuration being reloaded. We recommend working around this issue by deploying applications only in clusters that you launch using Rancher.

    • For more information on how to set up ingress in Rancher, see Ingress.
    • For complete information about ingress and ingress controllers, see the Kubernetes Ingress Documentation
    • When using ingresses in a project, you can program the ingress hostname to an external DNS by setting up a Global DNS entry.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/logging.html b/v2.5/pages-for-subheaders/logging.html index 95c784c69cc..efdbb6cf8fc 100644 --- a/v2.5/pages-for-subheaders/logging.html +++ b/v2.5/pages-for-subheaders/logging.html @@ -5,7 +5,7 @@ Rancher Integration with Logging Services | Rancher Manager - + @@ -14,7 +14,7 @@ Only Linux node logs are able to be exported.

    To allow the logging pods to be scheduled on Linux nodes, tolerations must be added to the pods. Refer to the Working with Taints and Tolerations section for details and an example.

    Working with a Custom Docker Root Directory​

    For details on using a custom Docker root directory, see this section.

    Working with Taints and Tolerations​

    For information on how to use taints and tolerations with the logging application, see this page.

    Logging V2 with SELinux​

    Available as of v2.5.8

    For information on enabling the logging application for SELinux-enabled nodes, see this section.

    Additional Logging Sources​

    By default, Rancher collects logs for control plane components and node components for all cluster types. In some cases additional logs can be collected. For details, see this section.

    Troubleshooting​

    The cattle-logging Namespace Being Recreated​

    If your cluster previously deployed logging from the Cluster Manager UI, you may encounter an issue where its cattle-logging namespace is continually being recreated.

    The solution is to delete all clusterloggings.management.cattle.io and projectloggings.management.cattle.io custom resources from the cluster specific namespace in the management cluster. The existence of these custom resources causes Rancher to create the cattle-logging namespace in the downstream cluster if it does not exist.

    The cluster namespace matches the cluster ID, so we need to find the cluster ID for each cluster.

    1. In your web browser, navigate to your cluster(s) in either the Cluster Manager UI or the Cluster Explorer UI.
    2. Copy the <cluster-id> portion from one of the URLs below. The <cluster-id> portion is the cluster namespace name.
    # Cluster Management UI
    https://<your-url>/c/<cluster-id>/

    # Cluster Explorer UI (Dashboard)
    https://<your-url>/dashboard/c/<cluster-id>/

    Now that we have the <cluster-id> namespace, we can delete the CRs that cause cattle-logging to be continually recreated. Warning: ensure that logging, the version installed from the Cluster Manager UI, is not currently in use.

    kubectl delete clusterloggings.management.cattle.io -n <cluster-id>
    kubectl delete projectloggings.management.cattle.io -n <cluster-id>
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/manage-clusters.html b/v2.5/pages-for-subheaders/manage-clusters.html index 1eaa3fb7a0d..b3b0c2ae83c 100644 --- a/v2.5/pages-for-subheaders/manage-clusters.html +++ b/v2.5/pages-for-subheaders/manage-clusters.html @@ -5,13 +5,13 @@ Cluster Administration | Rancher Manager - +
    Version: v2.5

    Cluster Administration

    After you provision a cluster in Rancher, you can begin using powerful Kubernetes features to deploy and scale your containerized applications in development, testing, or production environments.

    This page covers the following topics:

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    Switching between Clusters​

    To switch between clusters, use the drop-down available in the navigation bar.

    Alternatively, you can switch between projects and clusters directly in the navigation bar. Open the Global view and select Clusters from the main menu. Then select the name of the cluster you want to open.

    Managing Clusters in Rancher​

    After clusters have been provisioned into Rancher, cluster owners will need to manage these clusters. There are many different options of how to manage your cluster.

    ActionRancher Launched Kubernetes ClustersEKS and GKE Clusters1Other Hosted Kubernetes ClustersNon-EKS or GKE Registered Clusters
    Using kubectl and a kubeconfig file to Access a Cluster✓✓✓✓
    Managing Cluster Members✓✓✓✓
    Editing and Upgrading Clusters✓✓✓✓2
    Managing Nodes✓✓✓✓3
    Managing Persistent Volumes and Storage Classes✓✓✓✓
    Managing Projects, Namespaces and Workloads✓✓✓✓
    Using App Catalogs✓✓✓✓
    Configuring Tools (Alerts, Notifiers, Logging, Monitoring, Istio)✓✓✓✓
    Running Security Scans✓✓✓✓
    Use existing configuration to create additional clusters✓✓✓
    Ability to rotate certificates✓✓
    Ability to backup and restore Rancher-launched clusters✓✓✓4
    Cleaning Kubernetes components when clusters are no longer reachable from Rancher✓
    Configuring Pod Security Policies✓✓
    Authorized Cluster Endpoint✓

    1. Registered GKE and EKS clusters have the same options available as GKE and EKS clusters created from the Rancher UI. The difference is that when a registered cluster is deleted from the Rancher UI, it is not destroyed.

    2. Cluster configuration options can't be edited for registered clusters, except for K3s and RKE2 clusters.

    3. For registered cluster nodes, the Rancher UI exposes the ability to cordon, drain, and edit the node.

    4. For registered clusters using etcd as a control plane, snapshots must be taken manually outside of the Rancher UI to use for backup and recovery.

    Configuring Tools​

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently. Tools are divided into following categories:

    • Alerts
    • Notifiers
    • Logging
    • Monitoring
    • Istio Service Mesh
    • OPA Gatekeeper
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/manage-persistent-storage.html b/v2.5/pages-for-subheaders/manage-persistent-storage.html index 1ee0ff46b9d..a9805eda501 100644 --- a/v2.5/pages-for-subheaders/manage-persistent-storage.html +++ b/v2.5/pages-for-subheaders/manage-persistent-storage.html @@ -5,13 +5,13 @@ Manage Persistent Storage | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/manage-project-resource-quotas.html b/v2.5/pages-for-subheaders/manage-project-resource-quotas.html index ef831768c2a..c7afaee0730 100644 --- a/v2.5/pages-for-subheaders/manage-project-resource-quotas.html +++ b/v2.5/pages-for-subheaders/manage-project-resource-quotas.html @@ -5,13 +5,13 @@ Project Resource Quotas | Rancher Manager - +
    Version: v2.5

    Project Resource Quotas

    In situations where several teams share a cluster, one team may overconsume the resources available: CPU, memory, storage, services, Kubernetes objects like pods or secrets, and so on. To prevent this overconsumption, you can apply a resource quota, which is a Rancher feature that limits the resources available to a project or namespace.

    This page is a how-to guide for creating resource quotas in existing projects.

    Resource quotas can also be set when a new project is created. For details, refer to the section on creating new projects.

    Resource quotas in Rancher include the same functionality as the native version of Kubernetes. In Rancher, resource quotas have been extended so that you can apply them to projects. For details on how resource quotas work with projects in Rancher, refer to this page.

    Applying Resource Quotas to Existing Projects​

    Edit resource quotas when:

    • You want to limit the resources that a project and its namespaces can use.
    • You want to scale the resources available to a project up or down when a research quota is already in effect.

    1. From the Global view, open the cluster containing the project to which you want to apply a resource quota.

    2. From the main menu, select Projects/Namespaces.

    3. Find the project that you want to add a resource quota to. From that project, select ⋮ > Edit.

    4. Expand Resource Quotas and click Add Quota. Alternatively, you can edit existing quotas.

    5. Select a Resource Type. For more information on types, see the quota type reference.

    6. Enter values for the Project Limit and the Namespace Default Limit.

      FieldDescription
      Project LimitThe overall resource limit for the project.
      Namespace Default LimitThe default resource limit available for each namespace. This limit is propagated to each namespace in the project. The combined limit of all project namespaces shouldn't exceed the project limit.

    7. Optional: Add more quotas.

    8. Click Create.

    Result: The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/manage-projects.html b/v2.5/pages-for-subheaders/manage-projects.html index eecca96fbc3..a83a348eb20 100644 --- a/v2.5/pages-for-subheaders/manage-projects.html +++ b/v2.5/pages-for-subheaders/manage-projects.html @@ -5,13 +5,13 @@ Project Administration | Rancher Manager - +
    Version: v2.5

    Project Administration

    Projects are objects introduced in Rancher that help organize namespaces in your Kubernetes cluster. You can use projects to create multi-tenant clusters, which allows a group of users to share the same underlying resources without interacting with each other's applications.

    In terms of hierarchy:

    • Clusters contain projects
    • Projects contain namespaces

    Within Rancher, projects allow you to manage multiple namespaces as a single entity. In native Kubernetes, which does not include projects, features like role-based access rights or cluster resources are assigned to individual namespaces. In clusters where multiple namespaces require the same set of access rights, assigning these rights to each individual namespace can become tedious. Even though all namespaces require the same rights, there's no way to apply those rights to all of your namespaces in a single action. You'd have to repetitively assign these rights to each namespace!

    Rancher projects resolve this issue by allowing you to apply resources and access rights at the project level. Each namespace in the project then inherits these resources and policies, so you only have to assign them to the project once, rather than assigning them to each individual namespace.

    You can use projects to perform actions like:

    Authorization​

    Non-administrative users are only authorized for project access after an administrator, cluster owner or member, or project owner adds them to the project's Members tab.

    Whoever creates the project automatically becomes a project owner.

    Switching between Projects​

    To switch between projects, use the drop-down available in the navigation bar. Alternatively, you can switch between projects directly in the navigation bar.

    1. From the Global view, navigate to the project that you want to configure.

    2. Select Projects/Namespaces from the navigation bar.

    3. Select the link for the project that you want to open.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/manage-role-based-access-control-rbac.html b/v2.5/pages-for-subheaders/manage-role-based-access-control-rbac.html index 38bf779b56d..50b6d1b2a63 100644 --- a/v2.5/pages-for-subheaders/manage-role-based-access-control-rbac.html +++ b/v2.5/pages-for-subheaders/manage-role-based-access-control-rbac.html @@ -5,13 +5,13 @@ Role-Based Access Control (RBAC) | Rancher Manager - +
    Version: v2.5

    Role-Based Access Control (RBAC)

    Within Rancher, each person authenticates as a user, which is a login that grants you access to Rancher. As mentioned in Authentication, users can either be local or external.

    After you configure external authentication, the users that display on the Users page changes.

    • If you are logged in as a local user, only local users display.

    • If you are logged in as an external user, both external and local users display.

    Users and Roles​

    Once the user logs in to Rancher, their authorization, or their access rights within the system, is determined by global permissions, and cluster and project roles.

    • Global Permissions:

      Define user authorization outside the scope of any particular cluster.

    • Cluster and Project Roles:

      Define user authorization inside the specific cluster or project where they are assigned the role.

    Both global permissions and cluster and project roles are implemented on top of Kubernetes RBAC. Therefore, enforcement of permissions and roles is performed by Kubernetes.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/monitoring-alerting-guides.html b/v2.5/pages-for-subheaders/monitoring-alerting-guides.html index 5be47dd14be..6dc16e4e8dc 100644 --- a/v2.5/pages-for-subheaders/monitoring-alerting-guides.html +++ b/v2.5/pages-for-subheaders/monitoring-alerting-guides.html @@ -5,13 +5,13 @@ Monitoring Guides | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/monitoring-and-alerting.html b/v2.5/pages-for-subheaders/monitoring-and-alerting.html index 923ff3002c0..d2a4fb76102 100644 --- a/v2.5/pages-for-subheaders/monitoring-and-alerting.html +++ b/v2.5/pages-for-subheaders/monitoring-and-alerting.html @@ -5,13 +5,13 @@ Monitoring and Alerting | Rancher Manager - +
    Version: v2.5

    Monitoring and Alerting

    Using the rancher-monitoring application, you can quickly deploy leading open-source monitoring and alerting solutions onto your cluster.

    Features​

    Prometheus lets you view metrics from your Rancher and Kubernetes objects. Using timestamps, Prometheus lets you query and view these metrics in easy-to-read graphs and visuals, either through the Rancher UI or Grafana, which is an analytics viewing platform deployed along with Prometheus.

    By viewing data that Prometheus scrapes from your cluster control plane, nodes, and deployments, you can stay on top of everything happening in your cluster. You can then use these analytics to better run your organization: stop system emergencies before they start, develop maintenance strategies, or restore crashed servers.

    The rancher-monitoring operator, introduced in Rancher v2.5, is powered by Prometheus, Grafana, Alertmanager, the Prometheus Operator, and the Prometheus adapter.

    The monitoring application allows you to:

    • Monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments
    • Define alerts based on metrics collected via Prometheus
    • Create custom Grafana dashboards
    • Configure alert-based notifications via Email, Slack, PagerDuty, etc. using Prometheus Alertmanager
    • Defines precomputed, frequently needed or computationally expensive expressions as new time series based on metrics collected via Prometheus
    • Expose collected metrics from Prometheus to the Kubernetes Custom Metrics API via Prometheus Adapter for use in HPA

    How Monitoring Works

    For an explanation of how the monitoring components work together, see this page.

    Default Components and Deployments

    Built-in Dashboards​

    By default, the monitoring application deploys Grafana dashboards (curated by the kube-prometheus project) onto a cluster.

    It also deploys an Alertmanager UI and a Prometheus UI. For more information about these tools, see Built-in Dashboards.

    Default Metrics Exporters​

    By default, Rancher Monitoring deploys exporters (such as node-exporter and kube-state-metrics).

    These default exporters automatically scrape metrics for CPU and memory from all components of your Kubernetes cluster, including your workloads.

    Default Alerts​

    The monitoring application deploys some alerts by default. To see the default alerts, go to the Alertmanager UI and click Expand all groups.

    Components Exposed in the Rancher UI​

    For a list of monitoring components exposed in the Rancher UI, along with common use cases for editing them, see this section.

    Role-based Access Control

    For information on configuring access to monitoring, see this page.

    Guides

    Configuration

    Configuring Monitoring Resources in Rancher​

    The configuration reference assumes familiarity with how monitoring components work together. For more information, see How Monitoring Works.

    Configuring Helm Chart Options​

    For more information on rancher-monitoring chart options, including options to set resource limits and requests, see this page.

    Windows Cluster Support

    Available as of v2.5.8

    When deployed onto an RKE1 Windows cluster, Monitoring V2 will now automatically deploy a windows-exporter DaemonSet and set up a ServiceMonitor to collect metrics from each of the deployed Pods. This will populate Prometheus with windows_ metrics that are akin to the node_ metrics exported by node_exporter for Linux hosts.

    To be able to fully deploy Monitoring V2 for Windows, all of your Windows hosts must have a minimum wins version of v0.1.0.

    For more details on how to upgrade wins on existing Windows hosts, refer to the section on Windows cluster support for Monitoring V2.

    Known Issues

    There is a known issue that K3s clusters require more default memory. If you are enabling monitoring on a K3s cluster, we recommend setting prometheus.prometheusSpec.resources.memory.limit to 2500 Mi and prometheus.prometheusSpec.resources.memory.request to 1750 Mi.

    For tips on debugging high memory usage, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/monitoring-v2-configuration-guides.html b/v2.5/pages-for-subheaders/monitoring-v2-configuration-guides.html index ff4b93f87e6..2d3e58f7dce 100644 --- a/v2.5/pages-for-subheaders/monitoring-v2-configuration-guides.html +++ b/v2.5/pages-for-subheaders/monitoring-v2-configuration-guides.html @@ -5,13 +5,13 @@ Configuration | Rancher Manager - +
    Version: v2.5

    Configuration

    This page captures some of the most important options for configuring Monitoring V2 in the Rancher UI.

    For information on configuring custom scrape targets and rules for Prometheus, please refer to the upstream documentation for the Prometheus Operator. Some of the most important custom resources are explained in the Prometheus Operator design documentation. The Prometheus Operator documentation can help also you set up RBAC, Thanos, or custom configuration.

    Setting Resource Limits and Requests

    The resource requests and limits for the monitoring application can be configured when installing rancher-monitoring. For more information about the default limits, see this page.

    Note: On an idle cluster, Monitoring V2 has significantly higher CPU usage (up to 70%) as compared to Monitoring V1. To improve performance and achieve similar results as in Monitoring V1, turn off the Prometheus adapter.

    Prometheus Configuration

    It is usually not necessary to directly edit the Prometheus custom resource.

    Instead, to configure Prometheus to scrape custom metrics, you will only need to create a new ServiceMonitor or PodMonitor to configure Prometheus to scrape additional metrics.

    ServiceMonitor and PodMonitor Configuration​

    For details, see this page.

    Advanced Prometheus Configuration​

    For more information about directly editing the Prometheus custom resource, which may be helpful in advanced use cases, see this page.

    Alertmanager Configuration

    The Alertmanager custom resource usually doesn't need to be edited directly. For most common use cases, you can manage alerts by updating Routes and Receivers.

    Routes and receivers are part of the configuration of the alertmanager custom resource. In the Rancher UI, Routes and Receivers are not true custom resources, but pseudo-custom resources that the Prometheus Operator uses to synchronize your configuration with the Alertmanager custom resource. When routes and receivers are updated, the monitoring application will automatically update Alertmanager to reflect those changes.

    For some advanced use cases, you may want to configure alertmanager directly. For more information, refer to this page.

    Receivers​

    Receivers are used to set up notifications. For details on how to configure receivers, see this page.

    Routes​

    Routes filter notifications before they reach receivers. Each route needs to refer to a receiver that has already been configured. For details on how to configure routes, see this page.

    Advanced​

    For more information about directly editing the Alertmanager custom resource, which may be helpful in advanced use cases, see this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/monitoring-v2-configuration.html b/v2.5/pages-for-subheaders/monitoring-v2-configuration.html index c01975504dc..0062acf1764 100644 --- a/v2.5/pages-for-subheaders/monitoring-v2-configuration.html +++ b/v2.5/pages-for-subheaders/monitoring-v2-configuration.html @@ -5,13 +5,13 @@ Monitoring V2 Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/new-user-guides.html b/v2.5/pages-for-subheaders/new-user-guides.html index ceec3a2051a..a4dde2a9973 100644 --- a/v2.5/pages-for-subheaders/new-user-guides.html +++ b/v2.5/pages-for-subheaders/new-user-guides.html @@ -5,13 +5,13 @@ New User Guides | Rancher Manager - +
    Version: v2.5

    New User Guides

    New user guides, also known as tutorials, describe practical steps for users to follow in order to complete some concrete action. These docs are known as "learning-oriented" docs in which users learn by "doing".

    The new user guides are designed to guide beginners, or the everyday users of Rancher, through a series of steps to learn how to do something. The goal is that the user will be able to learn how to complete tasks by using easy-to-follow, meaningful, and repeatable directions. These guides will assist users to do work to then get the promised results immediately.

    The average Rancher user has a level of technical skill that is above the level of "beginner"; however, the new user guides are designed to help new, or beginner, users as well as the seasoned Rancher customer equally. This is accomplished by using a combination of high-level and technical language to introduce topics and guide the user through general tasks that are essential for every Rancher user to know.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/node-template-configuration.html b/v2.5/pages-for-subheaders/node-template-configuration.html index 2585a77ef58..dc8e1fbe74c 100644 --- a/v2.5/pages-for-subheaders/node-template-configuration.html +++ b/v2.5/pages-for-subheaders/node-template-configuration.html @@ -5,13 +5,13 @@ Node Template Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/other-cloud-providers.html b/v2.5/pages-for-subheaders/other-cloud-providers.html index 735a7de2855..06e851d759a 100644 --- a/v2.5/pages-for-subheaders/other-cloud-providers.html +++ b/v2.5/pages-for-subheaders/other-cloud-providers.html @@ -5,13 +5,13 @@ Other Cloud Providers | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/other-installation-methods.html b/v2.5/pages-for-subheaders/other-installation-methods.html index 178a8de84eb..bad68cfd24b 100644 --- a/v2.5/pages-for-subheaders/other-installation-methods.html +++ b/v2.5/pages-for-subheaders/other-installation-methods.html @@ -5,13 +5,13 @@ Other Installation Methods | Rancher Manager - +
    Version: v2.5

    Other Installation Methods

    Air Gapped Installations​

    Follow these steps to install the Rancher server in an air gapped environment.

    An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Docker Installations​

    The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

    The Docker installation is for development and testing environments only.

    Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    For Rancher v2.5+, the Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/other-troubleshooting-tips.html b/v2.5/pages-for-subheaders/other-troubleshooting-tips.html index 46ca3ecfb21..ad4d05f80a8 100644 --- a/v2.5/pages-for-subheaders/other-troubleshooting-tips.html +++ b/v2.5/pages-for-subheaders/other-troubleshooting-tips.html @@ -5,13 +5,13 @@ Other Troubleshooting Tips | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/pipelines.html b/v2.5/pages-for-subheaders/pipelines.html index 0553bb40b67..fe0fecca2b7 100644 --- a/v2.5/pages-for-subheaders/pipelines.html +++ b/v2.5/pages-for-subheaders/pipelines.html @@ -5,14 +5,14 @@ Pipelines | Rancher Manager - +
    Version: v2.5

    Pipelines

    As of Rancher v2.5, Git-based deployment pipelines are now deprecated. We recommend handling pipelines with Rancher Continuous Delivery powered by Fleet, available in Cluster Explorer.

    Notice: Fleet does not replace Rancher pipelines; the distinction is that Rancher pipelines are now powered by Fleet.

    Rancher's pipeline provides a simple CI/CD experience. Use it to automatically checkout code, run builds or scripts, publish Docker images or catalog applications, and deploy the updated software to users.

    Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Using Rancher, you can integrate with a GitHub repository to setup a continuous integration (CI) pipeline.

    After configuring Rancher and GitHub, you can deploy containers running Jenkins to automate a pipeline execution:

    • Build your application from code to image.
    • Validate your builds.
    • Deploy your build images to your cluster.
    • Run unit tests.
    • Run regression tests.

    Note: Rancher's pipeline provides a simple CI/CD experience, but it does not offer the full power and flexibility of and is not a replacement of enterprise-grade Jenkins or other CI tools your team uses.

    Concepts

    For an explanation of concepts and terminology used in this section, refer to this page.

    How Pipelines Work

    After enabling the ability to use pipelines in a project, you can configure multiple pipelines in each project. Each pipeline is unique and can be configured independently.

    A pipeline is configured off of a group of files that are checked into source code repositories. Users can configure their pipelines either through the Rancher UI or by adding a .rancher-pipeline.yml into the repository.

    Before pipelines can be configured, you will need to configure authentication to your version control provider, e.g. GitHub, GitLab, Bitbucket. If you haven't configured a version control provider, you can always use Rancher's example repositories to view some common pipeline deployments.

    When you configure a pipeline in one of your projects, a namespace specifically for the pipeline is automatically created. The following components are deployed to it:

    • Jenkins:

      The pipeline's build engine. Because project users do not directly interact with Jenkins, it's managed and locked.

      Note: There is no option to use existing Jenkins deployments as the pipeline engine.

    • Docker Registry:

      Out-of-the-box, the default target for your build-publish step is an internal Docker Registry. However, you can make configurations to push to a remote registry instead. The internal Docker Registry is only accessible from cluster nodes and cannot be directly accessed by users. Images are not persisted beyond the lifetime of the pipeline and should only be used in pipeline runs. If you need to access your images outside of pipeline runs, please push to an external registry.

    • Minio:

      Minio storage is used to store the logs for pipeline executions.

      Note: The managed Jenkins instance works statelessly, so don't worry about its data persistency. The Docker Registry and Minio instances use ephemeral volumes by default, which is fine for most use cases. If you want to make sure pipeline logs can survive node failures, you can configure persistent volumes for them, as described in data persistency for pipeline components.

    Roles-based Access Control for Pipelines

    If you can access a project, you can enable repositories to start building pipelines.

    Only administrators, cluster owners or members, or project owners can configure version control providers and manage global pipeline execution settings.

    Project members can only configure repositories and pipelines.

    Setting up Pipelines

    To set up pipelines, you will need to do the following:

    1. Configure version control providers
    2. Configure repositories
    3. Configure the pipeline

    1. Configure Version Control Providers​

    Before you can start configuring a pipeline for your repository, you must configure and authorize a version control provider:

    • GitHub
    • GitLab
    • Bitbucket

    Select your provider's tab below and follow the directions.

    1. From the Global view, navigate to the project that you want to configure pipelines.

    2. Select Tools > Pipelines in the navigation bar.

    3. Follow the directions displayed to Setup a Github application. Rancher redirects you to Github to setup an OAuth App in Github.

    4. From GitHub, copy the Client ID and Client Secret. Paste them into Rancher.

    5. If you're using GitHub for enterprise, select Use a private github enterprise installation. Enter the host address of your GitHub installation.

    6. Click Authenticate.

    Result: After the version control provider is authenticated, you will be automatically re-directed to start configuring which repositories you want start using with a pipeline.

    2. Configure Repositories​

    After the version control provider is authorized, you are automatically re-directed to start configuring which repositories that you want start using pipelines with. Even if someone else has set up the version control provider, you will see their repositories and can build a pipeline.

    1. From the Global view, navigate to the project that you want to configure pipelines.

    2. Click Resources > Pipelines.

    3. Click on Configure Repositories.

    4. A list of repositories are displayed. If you are configuring repositories the first time, click on Authorize & Fetch Your Own Repositories to fetch your repository list.

    5. For each repository that you want to set up a pipeline, click on Enable.

    6. When you're done enabling all your repositories, click on Done.

    Results: You have a list of repositories that you can start configuring pipelines for.

    3. Configure the Pipeline​

    Now that repositories are added to your project, you can start configuring the pipeline by adding automated stages and steps. For your convenience, there are multiple built-in step types for dedicated tasks.

    1. From the Global view, navigate to the project that you want to configure pipelines.

    2. Click Resources > Pipelines.

    3. Find the repository that you want to set up a pipeline for.

    4. Configure the pipeline through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml. Pipeline configuration is split into stages and steps. Stages must fully complete before moving onto the next stage, but steps in a stage run concurrently. For each stage, you can add different step types. Note: As you build out each step, there are different advanced options based on the step type. Advanced options include trigger rules, environment variables, and secrets. For more information on configuring the pipeline through the UI or the YAML file, refer to the pipeline configuration reference.

      • If you are going to use the UI, select the vertical ⋮ > Edit Config to configure the pipeline using the UI. After the pipeline is configured, you must view the YAML file and push it to the repository.
      • If you are going to use the YAML file, select the vertical ⋮ > View/Edit YAML to configure the pipeline. If you choose to use a YAML file, you need to push it to the repository after any changes in order for it to be updated in the repository. When editing the pipeline configuration, it takes a few moments for Rancher to check for an existing pipeline configuration.

    5. Select which branch to use from the list of branches.

    6. Optional: Set up notifications.

    7. Set up the trigger rules for the pipeline.

    8. Enter a Timeout for the pipeline.

    9. When all the stages and steps are configured, click Done.

    Results: Your pipeline is now configured and ready to be run.

    Pipeline Configuration Reference

    Refer to this page for details on how to configure a pipeline to:

    • Run a script
    • Build and publish images
    • Publish catalog templates
    • Deploy YAML
    • Deploy a catalog app

    The configuration reference also covers how to configure:

    • Notifications
    • Timeouts
    • The rules that trigger a pipeline
    • Environment variables
    • Secrets

    Running your Pipelines

    Run your pipeline for the first time. From the project view in Rancher, go to Resources > Pipelines. Find your pipeline and select the vertical ⋮ > Run.

    During this initial run, your pipeline is tested, and the following pipeline components are deployed to your project as workloads in a new namespace dedicated to the pipeline:

    • docker-registry
    • jenkins
    • minio

    This process takes several minutes. When it completes, you can view each pipeline component from the project Workloads tab.

    Triggering a Pipeline

    When a repository is enabled, a webhook is automatically set in the version control provider. By default, the pipeline is triggered by a push event to a repository, but you can modify the event(s) that trigger running the pipeline.

    Available Events:

    • Push: Whenever a commit is pushed to the branch in the repository, the pipeline is triggered.
    • Pull Request: Whenever a pull request is made to the repository, the pipeline is triggered.
    • Tag: When a tag is created in the repository, the pipeline is triggered.

    Note: This option doesn't exist for Rancher's example repositories.

    Modifying the Event Triggers for the Repository​

    1. From the Global view, navigate to the project that you want to modify the event trigger for the pipeline.

      1. Click Resources > Pipelines.

    3. Find the repository that you want to modify the event triggers. Select the vertical ⋮ > Setting.

    4. Select which event triggers (Push, Pull Request or Tag) you want for the repository.

    5. Click Save.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/provisioning-storage-examples.html b/v2.5/pages-for-subheaders/provisioning-storage-examples.html index 220cfdfdb44..46cbc0ae636 100644 --- a/v2.5/pages-for-subheaders/provisioning-storage-examples.html +++ b/v2.5/pages-for-subheaders/provisioning-storage-examples.html @@ -5,13 +5,13 @@ Provisioning Storage Examples | Rancher Manager - +
    Version: v2.5

    Provisioning Storage Examples

    Rancher supports persistent storage with a variety of volume plugins. However, before you use any of these plugins to bind persistent storage to your workloads, you have to configure the storage itself, whether its a cloud-based solution from a service-provider or an on-prem solution that you manage yourself.

    For your convenience, Rancher offers documentation on how to configure some of the popular storage methods:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/quick-start-guides.html b/v2.5/pages-for-subheaders/quick-start-guides.html index 654e81edd00..53643620db6 100644 --- a/v2.5/pages-for-subheaders/quick-start-guides.html +++ b/v2.5/pages-for-subheaders/quick-start-guides.html @@ -5,13 +5,13 @@ Rancher Deployment Quick Start Guides | Rancher Manager - +
    Version: v2.5

    Rancher Deployment Quick Start Guides

    Note: The intent of these guides is to quickly launch a sandbox that you can use to evaluate Rancher. These guides are not intended for production environments. For comprehensive setup instructions, see Installation.

    Howdy buckaroos! Use this section of the docs to jump start your deployment and testing of Rancher 2.x! It contains instructions for a simple Rancher setup and some common use cases. We plan on adding more content to this section in the future.

    We have Quick Start Guides for:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-behind-an-http-proxy.html b/v2.5/pages-for-subheaders/rancher-behind-an-http-proxy.html index e9e443303f4..e54e1775ee9 100644 --- a/v2.5/pages-for-subheaders/rancher-behind-an-http-proxy.html +++ b/v2.5/pages-for-subheaders/rancher-behind-an-http-proxy.html @@ -5,13 +5,13 @@ Installing Rancher behind an HTTP Proxy | Rancher Manager - +
    Version: v2.5

    Installing Rancher behind an HTTP Proxy

    In a lot of enterprise environments, servers or VMs running on premise do not have direct Internet access, but must connect to external services through a HTTP(S) proxy for security reasons. This tutorial shows step by step how to set up a highly available Rancher installation in such an environment.

    Alternatively, it is also possible to set up Rancher completely air-gapped without any Internet access. This process is described in detail in the Rancher docs.

    Installation Outline

    1. Set up infrastructure
    2. Set up a Kubernetes cluster
    3. Install Rancher
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-managed-clusters.html b/v2.5/pages-for-subheaders/rancher-managed-clusters.html index f6168d13b1f..33279d7a83b 100644 --- a/v2.5/pages-for-subheaders/rancher-managed-clusters.html +++ b/v2.5/pages-for-subheaders/rancher-managed-clusters.html @@ -5,13 +5,13 @@ Best Practices for Rancher Managed Clusters | Rancher Manager - +
    Version: v2.5

    Best Practices for Rancher Managed Clusters

    Logging​

    Refer to this guide for our recommendations for cluster-level logging and application logging.

    Monitoring​

    Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. Refer to this guide for our recommendations.

    Tips for Setting Up Containers​

    Running well-built containers can greatly impact the overall performance and security of your environment. Refer to this guide for tips.

    Best Practices for Rancher Managed vSphere Clusters​

    This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-manager-architecture.html b/v2.5/pages-for-subheaders/rancher-manager-architecture.html index e1eb8196383..20cab01653a 100644 --- a/v2.5/pages-for-subheaders/rancher-manager-architecture.html +++ b/v2.5/pages-for-subheaders/rancher-manager-architecture.html @@ -5,13 +5,13 @@ Architecture | Rancher Manager - +
    Version: v2.5

    Architecture

    This section focuses on the Rancher server and its components and how Rancher communicates with downstream Kubernetes clusters.

    For information on the different ways that Rancher can be installed, refer to the overview of installation options.

    For a list of main features of the Rancher API server, refer to the overview section.

    For guidance about setting up the underlying infrastructure for the Rancher server, refer to the architecture recommendations.

    note

    This section assumes a basic familiarity with Docker and Kubernetes. For a brief explanation of how Kubernetes components work together, refer to the concepts page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.html b/v2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.html index 1a0a41156f3..1870ea6f8dd 100644 --- a/v2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.html +++ b/v2.5/pages-for-subheaders/rancher-on-a-single-node-with-docker.html @@ -5,7 +5,7 @@ Installing Rancher on a Single Node Using Docker | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    Installing Rancher on a Single Node Using Docker

    Rancher can be installed by running a single Docker container.

    In this installation scenario, you'll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.

    Want to use an external load balancer? See Docker Install with an External Load Balancer instead.

    A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

    Privileged Access for Rancher v2.5+​

    When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the --privileged option.

    Requirements for OS, Docker, Hardware, and Networking

    Make sure that your node fulfills the general installation requirements.

    1. Provision Linux Host

    Provision a single Linux host according to our Requirements to launch your Rancher server.

    2. Choose an SSL Option and Install Rancher

    For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

    Do you want to...

    Choose from the following options:

    Option A: Default Rancher-generated Self-signed Certificate​

    If you are installing Rancher in a development or testing environment where identity verification isn't a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

    Log into your Linux host, and then run the minimum installation command below.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest

    Option B: Bring Your Own Certificate, Self-signed​

    In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they're connecting to your instance of Rancher.

    Prerequisites: Create a self-signed certificate using OpenSSL or another method of your choice.

    • The certificate files must be in PEM format.
    • In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    After creating your certificate, run the Docker command below to install Rancher. Use the -v flag and provide the path to your certificates to mount them in your container.

    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.
    <CA_CERTS.pem>The path to the certificate authority's certificate.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
      --privileged \
      rancher/rancher:latest

    Option C: Bring Your Own Certificate, Signed by a Recognized CA​

    In production environments where you're exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn't encounter security warnings.

    Prerequisites:

    • The certificate files must be in PEM format.
    • In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

    After obtaining your certificate, run the Docker command below.

    • Use the -v flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
    • Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.
    PlaceholderDescription
    <CERT_DIRECTORY>The path to the directory containing your certificate files.
    <FULL_CHAIN.pem>The path to your full certificate chain.
    <PRIVATE_KEY.pem>The path to the private key for your certificate.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
      -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
      --privileged \
      rancher/rancher:latest \
      --no-cacerts

    Option D: Let's Encrypt Certificate​

    Remember: Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let's Encrypt documentation on rate limits.

    For production environments, you also have the option of using Let's Encrypt certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, rancher.mydomain.com) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.

    Prerequisites:

    • Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
    • Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
    • Open port TCP/80 on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.

    After you fulfill the prerequisites, you can install Rancher using a Let's Encrypt certificate by running the following command.

    PlaceholderDescription
    <YOUR.DNS.NAME>Your domain address

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest \
      --acme-domain <YOUR.DNS.NAME>

    Advanced Options​

    When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:

    • Custom CA Certificate
    • API Audit Log
    • TLS Settings
    • Air Gap
    • Persistent Data
    • Running rancher/rancher and rancher/rancher-agent on the Same Node

    Refer to this page for details.

    Troubleshooting​

    Refer to this page for frequently asked questions and troubleshooting tips.

    What's Next?​

    • Recommended: Review Single Node Backup and Restore. Although you don't have any data you need to back up right now, we recommend creating backups after regular Rancher use.
    • Create a Kubernetes cluster: Provisioning Kubernetes Clusters.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-security.html b/v2.5/pages-for-subheaders/rancher-security.html index 1c5d6a26e49..9ee064cff28 100644 --- a/v2.5/pages-for-subheaders/rancher-security.html +++ b/v2.5/pages-for-subheaders/rancher-security.html @@ -5,13 +5,13 @@ Security | Rancher Manager - +
    Version: v2.5

    Security

    Security policy

    Rancher Labs supports responsible disclosure, and endeavours to resolve all issues in a reasonable time frame.

    Reporting process

    Please submit possible security issues by emailing security-rancher@suse.com .

    Announcements

    Subscribe to the Rancher announcements forum for release updates.

    Security is at the heart of all Rancher features. From integrating with all the popular authentication tools and services, to an enterprise grade RBAC capability, Rancher makes your Kubernetes clusters even more secure.

    On this page, we provide security related documentation along with resources to help you secure your Rancher installation and your downstream Kubernetes clusters.

    Running a CIS Security Scan on a Kubernetes Cluster​

    Rancher leverages kube-bench to run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS (Center for Internet Security) Kubernetes Benchmark.

    The CIS Kubernetes Benchmark is a reference document that can be used to establish a secure configuration baseline for Kubernetes.

    The Center for Internet Security (CIS) is a 501(c)(3) non-profit organization, formed in October 2000, with a mission to "identify, develop, validate, promote, and sustain best practice solutions for cyber defense and build and lead communities to enable an environment of trust in cyberspace".

    CIS Benchmarks are best practices for the secure configuration of a target system. CIS Benchmarks are developed through the generous volunteer efforts of subject matter experts, technology vendors, public and private community members, and the CIS Benchmark Development team.

    The Benchmark provides recommendations of two types: Automated and Manual. We run tests related to only Automated recommendations.

    When Rancher runs a CIS security scan on a cluster, it generates a report showing the results of each test, including a summary with the number of passed, skipped and failed tests. The report also includes remediation steps for any failed tests.

    For details, refer to the section on security scans.

    SELinux RPM​

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8.

    We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: rancher-selinux and rke2-selinux. For details, see this page.

    Rancher Hardening Guide​

    The Rancher Hardening Guide is based on controls and best practices found in the CIS Kubernetes Benchmark from the Center for Internet Security.

    The hardening guides provide prescriptive guidance for hardening a production installation of Rancher. See Rancher's guides for Self Assessment of the CIS Kubernetes Benchmark for the full list of security controls.

    The hardening guides describe how to secure the nodes in your cluster, and it is recommended to follow a hardening guide before installing Kubernetes.

    Each version of the hardening guide is intended to be used with specific versions of the CIS Kubernetes Benchmark, Kubernetes, and Rancher.

    The CIS Benchmark and Self-Assessment​

    The benchmark self-assessment is a companion to the Rancher security hardening guide. While the hardening guide shows you how to harden the cluster, the benchmark guide is meant to help you evaluate the level of security of the hardened cluster.

    Because Rancher and RKE install Kubernetes services as Docker containers, many of the control verification checks in the CIS Kubernetes Benchmark don't apply. This guide will walk through the various controls and provide updated example commands to audit compliance in Rancher created clusters. The original benchmark documents can be downloaded from the CIS website.

    Each version of Rancher's self-assessment guide corresponds to specific versions of the hardening guide, Rancher, Kubernetes, and the CIS Benchmark.

    Third-party Penetration Test Reports​

    Rancher periodically hires third parties to perform security audits and penetration tests of the Rancher 2.x software stack. The environments under test follow the Rancher provided hardening guides at the time of the testing. Results are posted when the third party has also verified fixes classified MEDIUM or above.

    Results:

    Rancher Security Advisories and CVEs​

    Rancher is committed to informing the community of security issues in our products. For the list of CVEs (Common Vulnerabilities and Exposures) for issues we have resolved, refer to this page.

    Kubernetes Security Best Practices​

    For recommendations on securing your Kubernetes cluster, refer to the Kubernetes Security Best Practices guide.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-server-configuration.html b/v2.5/pages-for-subheaders/rancher-server-configuration.html index 2a2a0110315..ce26ab68cd6 100644 --- a/v2.5/pages-for-subheaders/rancher-server-configuration.html +++ b/v2.5/pages-for-subheaders/rancher-server-configuration.html @@ -5,13 +5,13 @@ Rancher Server Configuration | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-server.html b/v2.5/pages-for-subheaders/rancher-server.html index 39762a3f0cb..ff9a49150d2 100644 --- a/v2.5/pages-for-subheaders/rancher-server.html +++ b/v2.5/pages-for-subheaders/rancher-server.html @@ -5,13 +5,13 @@ Best Practices for the Rancher Server | Rancher Manager - +
    Version: v2.5

    Best Practices for the Rancher Server

    This guide contains our recommendations for running the Rancher server, and is intended to be used in situations in which Rancher manages downstream Kubernetes clusters.

    Refer to this guide for our general advice for setting up the Rancher server on a high-availability Kubernetes cluster.

    Deployment Strategies​

    This guide is designed to help you choose whether a regional deployment strategy or a hub-and-spoke deployment strategy is better for a Rancher server that manages downstream Kubernetes clusters.

    Installing Rancher in a vSphere Environment​

    This guide outlines a reference architecture for installing Rancher in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/rancher-v2.5-hardening-guides.html b/v2.5/pages-for-subheaders/rancher-v2.5-hardening-guides.html index c692d6b1596..e3e8a0207c6 100644 --- a/v2.5/pages-for-subheaders/rancher-v2.5-hardening-guides.html +++ b/v2.5/pages-for-subheaders/rancher-v2.5-hardening-guides.html @@ -5,13 +5,13 @@ Self-Assessment and Hardening Guides for Rancher v2.5 | Rancher Manager - +
    Version: v2.5

    Self-Assessment and Hardening Guides for Rancher v2.5

    Rancher v2.5 introduced the capability to deploy Rancher on any Kubernetes cluster. For that reason, we now provide separate security hardening guides for Rancher deployments on each of Rancher's Kubernetes distributions.

    Rancher Kubernetes Distributions​

    Rancher has the following Kubernetes distributions:

    • RKE, Rancher Kubernetes Engine, is a CNCF-certified Kubernetes distribution that runs entirely within Docker containers.
    • K3s, is a fully conformant, lightweight Kubernetes distribution. It is easy to install, with half the memory of upstream Kubernetes, all in a binary of less than 100 MB.
    • RKE2 is a fully conformant Kubernetes distribution that focuses on security and compliance within the U.S. Federal Government sector.

    To harden a Kubernetes cluster outside of Rancher's distributions, refer to your Kubernetes provider docs.

    Hardening Guides and Benchmark Versions​

    These guides have been tested along with the Rancher v2.5 release. Each self-assessment guide is accompanied with a hardening guide and tested on a specific Kubernetes version and CIS benchmark version. If a CIS benchmark has not been validated for your Kubernetes version, you can choose to use the existing guides until a newer version is added.

    RKE Guides​

    Kubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guides
    Kubernetes v1.15+CIS v1.5LinkLink
    Kubernetes v1.18+CIS v1.6LinkLink

    RKE2 Guides​

    Kubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guides
    Kubernetes v1.18CIS v1.5LinkLink
    Kubernetes v1.20CIS v1.6LinkLink

    K3s Guides​

    Kubernetes VersionCIS Benchmark VersionSelf Assessment GuideHardening Guide
    Kubernetes v1.17, v1.18, & v1.19CIS v1.5LinkLink

    Rancher with SELinux​

    Available as of v2.5.8

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux. After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8.

    To use Rancher with SELinux, we recommend installing the rancher-selinux RPM according to the instructions on this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/resources.html b/v2.5/pages-for-subheaders/resources.html index 760470ceab8..eacca082181 100644 --- a/v2.5/pages-for-subheaders/resources.html +++ b/v2.5/pages-for-subheaders/resources.html @@ -5,13 +5,13 @@ Resources | Rancher Manager - +
    Version: v2.5

    Resources

    Docker Installations​

    The single-node Docker installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster using Helm, you install the Rancher server component on a single node using a docker run command.

    Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server.

    Air Gapped Installations​

    Follow these steps to install the Rancher server in an air gapped environment.

    An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy.

    Advanced Options​

    When installing Rancher, there are several advanced options that can be enabled during installation. Within each install guide, these options are presented. Learn more about these options:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/selinux-rpm.html b/v2.5/pages-for-subheaders/selinux-rpm.html index 356a5fae2f6..c24c9f0414a 100644 --- a/v2.5/pages-for-subheaders/selinux-rpm.html +++ b/v2.5/pages-for-subheaders/selinux-rpm.html @@ -5,13 +5,13 @@ SELinux RPM | Rancher Manager - +
    Version: v2.5

    SELinux RPM

    Available as of v2.5.8

    Security-Enhanced Linux (SELinux) is a security enhancement to Linux.

    Developed by Red Hat, it is an implementation of mandatory access controls (MAC) on Linux. Mandatory access controls allow an administrator of a system to define how applications and users can access different resources such as files, devices, networks and inter-process communication. SELinux also enhances security by making an OS restrictive by default.

    After being historically used by government agencies, SELinux is now industry standard and is enabled by default on CentOS 7 and 8. To check whether SELinux is enabled and enforcing on your system, use getenforce:

    # getenforce
    Enforcing

    We provide two RPMs (Red Hat packages) that enable Rancher products to function properly on SELinux-enforcing hosts: rancher-selinux and rke2-selinux.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/set-up-cloud-providers.html b/v2.5/pages-for-subheaders/set-up-cloud-providers.html index fe28ebb0dc1..3eebeea7d29 100644 --- a/v2.5/pages-for-subheaders/set-up-cloud-providers.html +++ b/v2.5/pages-for-subheaders/set-up-cloud-providers.html @@ -5,13 +5,13 @@ Setting up Cloud Providers | Rancher Manager - +
    Version: v2.5

    Setting up Cloud Providers

    A cloud provider is a module in Kubernetes that provides an interface for managing nodes, load balancers, and networking routes.

    When a cloud provider is set up in Rancher, the Rancher server can automatically provision new nodes, load balancers or persistent storage devices when launching Kubernetes definitions, if the cloud provider you're using supports such automation.

    Your cluster will not provision correctly if you configure a cloud provider cluster of nodes that do not meet the prerequisites.

    By default, the Cloud Provider option is set to None.

    The following cloud providers can be enabled:

    • Amazon
    • Azure
    • GCE (Google Compute Engine)
    • vSphere

    Setting up the Amazon Cloud Provider​

    For details on enabling the Amazon cloud provider, refer to this page.

    Setting up the Azure Cloud Provider​

    For details on enabling the Azure cloud provider, refer to this page.

    Setting up the GCE Cloud Provider​

    For details on enabling the Google Compute Engine cloud provider, refer to this page.

    Setting up the vSphere Cloud Provider​

    For details on enabling the vSphere cloud provider, refer to this page.

    Setting up a Custom Cloud Provider​

    The Custom cloud provider is available if you want to configure any Kubernetes cloud provider.

    For the custom cloud provider option, you can refer to the RKE docs on how to edit the yaml file for your specific cloud provider. There are specific cloud providers that have more detailed configuration:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html b/v2.5/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html index 127a3879f3a..74726d3d155 100644 --- a/v2.5/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html +++ b/v2.5/pages-for-subheaders/set-up-clusters-from-hosted-kubernetes-providers.html @@ -5,13 +5,13 @@ Setting up Clusters from Hosted Kubernetes Providers | Rancher Manager - +
    Version: v2.5

    Setting up Clusters from Hosted Kubernetes Providers

    In this scenario, Rancher does not provision Kubernetes because it is installed by providers such as Google Kubernetes Engine (GKE), Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    If you use a Kubernetes provider such as Google GKE, Rancher integrates with its cloud APIs, allowing you to create and manage role-based access control for the hosted cluster from the Rancher UI.

    In this use case, Rancher sends a request to a hosted provider using the provider's API. The provider then provisions and hosts the cluster for you. When the cluster finishes building, you can manage it from the Rancher UI along with clusters you've provisioned that are hosted on-prem or in an infrastructure provider.

    Rancher supports the following Kubernetes providers:

    Hosted Kubernetes Provider Authentication​

    When using Rancher to create a cluster hosted by a provider, you are prompted for authentication information. This information is required to access the provider's API. For more information on how to obtain this information, see the following procedures:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/single-node-rancher-in-docker.html b/v2.5/pages-for-subheaders/single-node-rancher-in-docker.html index ce4e2cea44e..42ecda9d935 100644 --- a/v2.5/pages-for-subheaders/single-node-rancher-in-docker.html +++ b/v2.5/pages-for-subheaders/single-node-rancher-in-docker.html @@ -5,13 +5,13 @@ Single Node Rancher in Docker | Rancher Manager - +
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/use-existing-nodes.html b/v2.5/pages-for-subheaders/use-existing-nodes.html index e363e8cc284..608dda8cc15 100644 --- a/v2.5/pages-for-subheaders/use-existing-nodes.html +++ b/v2.5/pages-for-subheaders/use-existing-nodes.html @@ -5,13 +5,13 @@ Launching Kubernetes on Existing Custom Nodes | Rancher Manager - +
    Version: v2.5

    Launching Kubernetes on Existing Custom Nodes

    When you create a custom cluster, Rancher uses RKE (the Rancher Kubernetes Engine) to create a Kubernetes cluster in on-prem bare-metal servers, on-prem virtual machines, or in any node hosted by an infrastructure provider.

    To use this option you'll need access to servers you intend to use in your Kubernetes cluster. Provision each server according to the requirements, which includes some hardware specifications and Docker. After you install Docker on each server, you willl also run the command provided in the Rancher UI on each server to turn each one into a Kubernetes node.

    This section describes how to set up a custom cluster.

    Creating a Cluster with Custom Nodes

    Want to use Windows hosts as Kubernetes workers?

    See Configuring Custom Clusters for Windows before you start.

    1. Provision a Linux Host​

    Begin creation of a custom cluster by provisioning a Linux host. Your host can be:

    • A cloud-host virtual machine (VM)
    • An on-prem VM
    • A bare-metal server

    If you want to reuse a node from a previous custom cluster, clean the node before using it in a cluster again. If you reuse a node that hasn't been cleaned, cluster provisioning may fail.

    Provision the host according to the installation requirements and the checklist for production-ready clusters.

    2. Create the Custom Cluster​

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    1. From the Clusters page, click Add Cluster.

    2. Choose Custom.

    3. Enter a Cluster Name.

    4. Use Member Roles to configure user authorization for the cluster. Click Add Member to add users that can access the cluster. Use the Role drop-down to set permissions for each user.

    5. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options.

      Using Windows nodes as Kubernetes workers?

    6. Click **Next**.

    7. From Node Role, choose the roles that you want filled by a cluster node. You must provision at least one node for each role: etcd, worker, and control plane. All three roles are required for a custom cluster to finish provisioning. For more information on roles, see this section.

      Notes:

      • Using Windows nodes as Kubernetes workers? See this section.
      • Bare-Metal Server Reminder: If you plan on dedicating bare-metal servers to each role, you must provision a bare-metal server for each role (i.e. provision multiple bare-metal servers).
    8. **Optional**: Click **[Show advanced options](admin-settings/agent-options/)** to specify IP address(es) to use when registering the node, override the hostname of the node, or to add [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) or [taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) to the node.

    9. Copy the command displayed on screen to your clipboard.

    10. Log in to your Linux host using your preferred shell, such as PuTTy or a remote Terminal connection. Run the command copied to your clipboard.

      Note: Repeat steps 7-10 if you want to dedicate specific hosts to specific node roles. Repeat the steps as many times as needed.

    11. When you finish running the command(s) on your Linux host(s), click Done.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    3. Amazon Only: Tag Resources​

    If you have configured your cluster to use Amazon as Cloud Provider, tag your AWS resources with a cluster ID.

    Amazon Documentation: Tagging Your Amazon EC2 Resources

    Note: You can use Amazon EC2 instances without configuring a cloud provider in Kubernetes. You only have to configure the cloud provider if you want to use specific Kubernetes cloud provider functionality. For more information, see Kubernetes Cloud Providers

    The following resources need to be tagged with a ClusterID:

    • Nodes: All hosts added in Rancher.

    • Subnet: The subnet used for your cluster

    • Security Group: The security group used for your cluster.

      Note: Do not tag multiple security groups. Tagging multiple groups generates an error when creating Elastic Load Balancer.

    The tag that should be used is:

    Key=kubernetes.io/cluster/<CLUSTERID>, Value=owned

    <CLUSTERID> can be any string you choose. However, the same string must be used on every resource you tag. Setting the tag value to owned informs the cluster that all resources tagged with the <CLUSTERID> are owned and managed by this cluster.

    If you share resources between clusters, you can change the tag to:

    Key=kubernetes.io/cluster/CLUSTERID, Value=shared

    Optional Next Steps

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html b/v2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html index 641946fa747..d0631ced39f 100644 --- a/v2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html +++ b/v2.5/pages-for-subheaders/use-new-nodes-in-an-infra-provider.html @@ -5,13 +5,13 @@ Launching Kubernetes on New Nodes in an Infrastructure Provider | Rancher Manager - +
    Version: v2.5

    Launching Kubernetes on New Nodes in an Infrastructure Provider

    Using Rancher, you can create pools of nodes based on a node template. This node template defines the parameters you want to use to launch nodes in your infrastructure providers or cloud providers.

    One benefit of installing Kubernetes on node pools hosted by an infrastructure provider is that if a node loses connectivity with the cluster, Rancher can automatically create another node to join the cluster to ensure that the count of the node pool is as expected.

    The available cloud providers to create a node template are decided based on active node drivers.

    Node Templates

    A node template is the saved configuration for the parameters to use when provisioning nodes in a specific cloud provider. These nodes can be launched from the UI. Rancher uses Docker Machine to provision these nodes. The available cloud providers to create node templates are based on the active node drivers in Rancher.

    After you create a node template in Rancher, it's saved so that you can use this template again to create node pools. Node templates are bound to your login. After you add a template, you can remove them from your user profile.

    Node Labels​

    You can add labels on each node template, so that any nodes created from the node template will automatically have these labels on them.

    Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.

    Node Taints​

    You can add taints on each node template, so that any nodes created from the node template will automatically have these taints on them.

    Since taints can be added at a node template and node pool, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

    Administrator Control of Node Templates​

    Administrators can control all node templates. Admins can now maintain all the node templates within Rancher. When a node template owner is no longer using Rancher, the node templates created by them can be managed by administrators so the cluster can continue to be updated and maintained.

    To access all node templates, an administrator will need to do the following:

    1. In the Rancher UI, click the user profile icon in the upper right corner.
    2. Click Node Templates.

    Result: All node templates are listed and grouped by owner. The templates can be edited or cloned by clicking the ⋮.

    Node Pools

    Using Rancher, you can create pools of nodes based on a node template.

    A node template defines the configuration of a node, like what operating system to use, number of CPUs and amount of memory.

    The benefit of using a node pool is that if a node is destroyed or deleted, you can increase the number of live nodes to compensate for the node that was lost. The node pool helps you ensure that the count of the node pool is as expected.

    Each node pool must have one or more nodes roles assigned.

    Each node role (i.e. etcd, control plane, and worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.

    The recommended setup is to have:

    • a node pool with the etcd node role and a count of three
    • a node pool with the control plane node role and a count of at least two
    • a node pool with the worker node role and a count of at least two

    Node Pool Taints​

    If you haven't defined taints on your node template, you can add taints for each node pool. The benefit of adding taints at a node pool is beneficial over adding it at a node template is that you can swap out the node templates without worrying if the taint is on the node template.

    For each taint, they will automatically be added to any created node in the node pool. Therefore, if you add taints to a node pool that have existing nodes, the taints won't apply to existing nodes in the node pool, but any new node added into the node pool will get the taint.

    When there are taints on the node pool and node template, if there is no conflict with the same key and effect of the taints, all taints will be added to the nodes. If there are taints with the same key and different effect, the taints from the node pool will override the taints from the node template.

    About Node Auto-replace​

    If a node is in a node pool, Rancher can automatically replace unreachable nodes. Rancher will use the existing node template for the given node pool to recreate the node if it becomes inactive for a specified number of minutes.

    Important: Self-healing node pools are designed to help you replace worker nodes for stateless applications. It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

    Node auto-replace works on top of the Kubernetes node controller. The node controller periodically checks the status of all the nodes (configurable via the --node-monitor-period flag of the kube-controller). When a node is unreachable, the node controller will taint that node. When this occurs, Rancher will begin its deletion countdown. You can configure the amount of time Rancher waits to delete the node. If the taint is not removed before the deletion countdown ends, Rancher will proceed to delete the node object. Rancher will then provision a node in accordance with the set quantity of the node pool.

    Enabling Node Auto-replace​

    When you create the node pool, you can specify the amount of time in minutes that Rancher will wait to replace an unresponsive node.

    1. In the form for creating a cluster, go to the Node Pools section.
    2. Go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
    3. Fill out the rest of the form for creating a cluster.

    Result: Node auto-replace is enabled for the node pool.

    You can also enable node auto-replace after the cluster is created with the following steps:

    1. From the Global view, click the Clusters tab.
    2. Go to the cluster where you want to enable node auto-replace, click the vertical ⋮ (…), and click Edit.
    3. In the Node Pools section, go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter the number of minutes that Rancher should wait for a node to respond before replacing the node.
    4. Click Save.

    Result: Node auto-replace is enabled for the node pool.

    Disabling Node Auto-replace​

    You can disable node auto-replace from the Rancher UI with the following steps:

    1. From the Global view, click the Clusters tab.
    2. Go to the cluster where you want to enable node auto-replace, click the vertical ⋮ (…), and click Edit.
    3. In the Node Pools section, go to the node pool where you want to enable node auto-replace. In the Recreate Unreachable After field, enter 0.
    4. Click Save.

    Result: Node auto-replace is disabled for the node pool.

    Cloud Credentials

    Node templates can use cloud credentials to store credentials for launching nodes in your cloud provider, which has some benefits:

    • Credentials are stored as a Kubernetes secret, which is not only more secure, but it also allows you to edit a node template without having to enter your credentials every time.

    • After the cloud credential is created, it can be re-used to create additional node templates.

    • Multiple node templates can share the same cloud credential to create node pools. If your key is compromised or expired, the cloud credential can be updated in a single place, which allows all node templates that are using it to be updated at once.

    After cloud credentials are created, the user can start managing the cloud credentials that they created.

    Node Drivers

    If you don't find the node driver that you want to use, you can see if it is available in Rancher's built-in node drivers and activate it, or you can add your own custom node driver.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/use-windows-clusters.html b/v2.5/pages-for-subheaders/use-windows-clusters.html index 9488af8bc50..14acd9d2fe7 100644 --- a/v2.5/pages-for-subheaders/use-windows-clusters.html +++ b/v2.5/pages-for-subheaders/use-windows-clusters.html @@ -5,13 +5,13 @@ Launching Kubernetes on Windows Clusters | Rancher Manager - +
    Version: v2.5

    Launching Kubernetes on Windows Clusters

    When provisioning a custom cluster using Rancher, Rancher uses RKE (the Rancher Kubernetes Engine) to install Kubernetes on your existing nodes.

    In a Windows cluster provisioned with Rancher, the cluster must contain both Linux and Windows nodes. The Kubernetes controlplane can only run on Linux nodes, and the Windows nodes can only have the worker role. Windows nodes can only be used for deploying workloads.

    Some other requirements for Windows clusters include:

    • You can only add Windows nodes to a cluster if Windows support is enabled when the cluster is created. Windows support cannot be enabled for existing clusters.
    • Kubernetes 1.15+ is required.
    • The Flannel network provider must be used.
    • Windows nodes must have 50 GB of disk space.

    For the full list of requirements, see this section.

    For a summary of Kubernetes features supported in Windows, see the Kubernetes documentation on supported functionality and limitations for using Kubernetes with Windows or the guide for scheduling Windows containers in Kubernetes.

    Requirements for Windows Clusters

    The general node requirements for networking, operating systems, and Docker are the same as the node requirements for a Rancher installation.

    OS and Docker Requirements​

    Our support for Windows Server and Windows containers match the Microsoft official lifecycle for LTSC (Long-Term Servicing Channel) and SAC (Semi-Annual Channel).

    For the support lifecycle dates for Windows Server, see the Microsoft Documentation.

    Kubernetes Version​

    Kubernetes v1.15+ is required.

    Node Requirements​

    The hosts in the cluster need to have at least:

    • 2 core CPUs
    • 5 GB memory
    • 50 GB disk space

    Rancher will not provision the node if the node does not meet these requirements.

    Networking Requirements​

    Before provisioning a new cluster, be sure that you have already installed Rancher on a device that accepts inbound network traffic. This is required in order for the cluster nodes to communicate with Rancher. If you have not already installed Rancher, please refer to the installation documentation before proceeding with this guide.

    Rancher only supports Windows using Flannel as the network provider.

    There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.

    For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

    For VXLAN (Overlay) networking, the KB4489899 hotfix must be installed. Most cloud-hosted VMs already have this hotfix.

    If you are configuring DHCP options sets for an AWS virtual private cloud, note that in the domain-name option field, only one domain name can be specified. According to the DHCP options documentation:

    Some Linux operating systems accept multiple domain names separated by spaces. However, other Linux operating systems and Windows treat the value as a single domain, which results in unexpected behavior. If your DHCP options set is associated with a VPC that has instances with multiple operating systems, specify only one domain name.

    Rancher on vSphere with ESXi 6.7u2 and above​

    If you are using Rancher on VMware vSphere with ESXi 6.7u2 or later with Red Hat Enterprise Linux 8.3, CentOS 8.3, or SUSE Enterprise Linux 15 SP2 or later, it is necessary to disable the vmxnet3 virtual network adapter hardware offloading feature. Failure to do so will result in all network connections between pods on different cluster nodes to fail with timeout errors. All connections from Windows pods to critical services running on Linux nodes, such as CoreDNS, will fail as well. It is also possible that external connections may fail. This issue is the result of Linux distributions enabling the hardware offloading feature in vmxnet3 and a bug in the vmxnet3 hardware offloading feature that results in the discarding of packets for guest overlay traffic. To address this issue, it is necessary disable the vmxnet3 hardware offloading feature. This setting does not survive reboot, so it is necessary to disable on every boot. The recommended course of action is to create a systemd unit file at /etc/systemd/system/disable_hw_offloading.service, which disables the vmxnet3 hardware offloading feature on boot. A sample systemd unit file which disables the vmxnet3 hardware offloading feature is as follows. Note that <VM network interface> must be customized to the host vmxnet3 network interface, e.g., ens192:

    [Unit]
    Description=Disable vmxnet3 hardware offloading feature

    [Service]
    Type=oneshot
    ExecStart=ethtool -K <VM network interface> tx-udp_tnl-segmentation off
    ExecStart=ethtool -K <VM network interface> tx-udp_tnl-csum-segmentation off
    StandardOutput=journal

    [Install]
    WantedBy=multi-user.target

    Then set the appropriate permissions on the systemd unit file:

    chmod 0644 /etc/systemd/system/disable_hw_offloading.service

    Finally, enable the systemd service:

    systemctl enable disable_hw_offloading.service

    Architecture Requirements​

    The Kubernetes cluster management nodes (etcd and controlplane) must be run on Linux nodes.

    The worker nodes, which is where your workloads will be deployed on, will typically be Windows nodes, but there must be at least one worker node that is run on Linux in order to run the Rancher cluster agent, DNS, metrics server, and Ingress related containers.

    Clusters won't begin provisioning until all three node roles (worker, etcd and controlplane) are present.

    We recommend the minimum three-node architecture listed in the table below, but you can always add additional Linux and Windows workers to scale up your cluster for redundancy:

    NodeOperating SystemKubernetes Cluster Role(s)Purpose
    Node 1Linux (Ubuntu Server 18.04 recommended)Control plane, etcd, workerManage the Kubernetes cluster
    Node 2Linux (Ubuntu Server 18.04 recommended)WorkerSupport the Rancher Cluster agent, Metrics server, DNS, and Ingress for the cluster
    Node 3Windows (Windows Server core version 1809 or above)WorkerRun your Windows containers

    Container Requirements​

    Windows requires that containers must be built on the same Windows Server version that they are being deployed on. Therefore, containers must be built on Windows Server core version 1809 or above. If you have existing containers built for an earlier Windows Server core version, they must be re-built on Windows Server core version 1809 or above.

    Cloud Provider Specific Requirements​

    If you set a Kubernetes cloud provider in your cluster, some additional steps are required. You might want to set a cloud provider if you want to want to leverage a cloud provider's capabilities, for example, to automatically provision storage, load balancers, or other infrastructure for your cluster. Refer to this page for details on how to configure a cloud provider cluster of nodes that meet the prerequisites.

    If you are using the GCE (Google Compute Engine) cloud provider, you must do the following:

    • Enable the GCE cloud provider in the cluster.yml by following these steps.
    • When provisioning the cluster in Rancher, choose Custom cloud provider as the cloud provider in the Rancher UI.

    Tutorial: How to Create a Cluster with Windows Support

    This tutorial describes how to create a Rancher-provisioned cluster with the three nodes in the recommended architecture.

    When you provision a cluster with Rancher on existing nodes, you will add nodes to the cluster by installing the Rancher agent on each one. When you create or edit your cluster from the Rancher UI, you will see a Customize Node Run Command that you can run on each server to add it to your cluster.

    To set up a cluster with support for Windows nodes and containers, you will need to complete the tasks below.

    1. Provision Hosts

    To begin provisioning a cluster on existing nodes with Windows support, prepare your hosts.

    Your hosts can be:

    • Cloud-hosted VMs
    • VMs from virtualization clusters
    • Bare-metal servers

    You will provision three nodes:

    • One Linux node, which manages the Kubernetes control plane and stores your etcd
    • A second Linux node, which will be another worker node
    • The Windows node, which will run your Windows containers as a worker node
    NodeOperating System
    Node 1Linux (Ubuntu Server 18.04 recommended)
    Node 2Linux (Ubuntu Server 18.04 recommended)
    Node 3Windows (Windows Server core version 1809 or above required)

    If your nodes are hosted by a Cloud Provider and you want automation support such as loadbalancers or persistent storage devices, your nodes have additional configuration requirements. For details, see Selecting Cloud Providers.

    2. Create the Cluster on Existing Nodes

    The instructions for creating a Windows cluster on existing nodes are very similar to the general instructions for creating a custom cluster with some Windows-specific requirements.

    1. From the Global view, click on the Clusters tab and click Add Cluster.
    2. Click From existing nodes (Custom).
    3. Enter a name for your cluster in the Cluster Name text box.
    4. In the Kubernetes Version dropdown menu, select v1.15 or above.
    5. In the Network Provider field, select Flannel.
    6. In the Windows Support section, click Enable.
    7. Optional: After you enable Windows support, you will be able to choose the Flannel backend. There are two network options: Host Gateway (L2bridge) and VXLAN (Overlay). The default option is VXLAN (Overlay) mode.
    8. Click Next.

    Important: For Host Gateway (L2bridge) networking, it's best to use the same Layer 2 network for all nodes. Otherwise, you need to configure the route rules for them. For details, refer to the documentation on configuring cloud-hosted VM routes. You will also need to disable private IP address checks if you are using Amazon EC2, Google GCE, or Azure VM.

    3. Add Nodes to the Cluster

    This section describes how to register your Linux and Worker nodes to your cluster. You will run a command on each node, which will install the Rancher agent and allow Rancher to manage each node.

    Add Linux Master Node​

    In this section, we fill out a form on the Rancher UI to get a custom command to install the Rancher agent on the Linux master node. Then we will copy the command and run it on our Linux master node to register the node in the cluster.

    The first node in your cluster should be a Linux host has both the Control Plane and etcd roles. At a minimum, both of these roles must be enabled for this node, and this node must be added to your cluster before you can add Windows hosts.

    1. In the Node Operating System section, click Linux.
    2. In the Node Role section, choose at least etcd and Control Plane. We recommend selecting all three.
    3. Optional: If you click Show advanced options, you can customize the settings for the Rancher agent and node labels.
    4. Copy the command displayed on the screen to your clipboard.
    5. SSH into your Linux host and run the command that you copied to your clipboard.
    6. When you are finished provisioning your Linux node(s), select Done.

    Result:

    Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.

    You can access your cluster after its state is updated to Active.

    Active clusters are assigned two Projects:

    • Default, containing the default namespace
    • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces

    It may take a few minutes for the node to be registered in your cluster.

    Add Linux Worker Node​

    In this section, we run a command to register the Linux worker node to the cluster.

    After the initial provisioning of your cluster, your cluster only has a single Linux host. Next, we add another Linux worker host, which will be used to support Rancher cluster agent, Metrics server, DNS and Ingress for your cluster.

    1. From the Global view, click Clusters.
    2. Go to the cluster that you created and click ⋮ > Edit.
    3. Scroll down to Node Operating System. Choose Linux.
    4. In the Customize Node Run Command section, go to the Node Options and select the Worker role.
    5. Copy the command displayed on screen to your clipboard.
    6. Log in to your Linux host using a remote Terminal connection. Run the command copied to your clipboard.
    7. From Rancher, click Save.

    Result: The Worker role is installed on your Linux host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster.

    Note: Taints on Linux Worker Nodes

    For each Linux worker node added into the cluster, the following taints will be added to Linux worker node. By adding this taint to the Linux worker node, any workloads added to the Windows cluster will be automatically scheduled to the Windows worker node. If you want to schedule workloads specifically onto the Linux worker node, you will need to add tolerations to those workloads.

    Taint KeyTaint ValueTaint Effect
    cattle.io/oslinuxNoSchedule

    Add a Windows Worker Node​

    In this section, we run a command to register the Windows worker node to the cluster.

    You can add Windows hosts to the cluster by editing the cluster and choosing the Windows option.

    1. From the Global view, click Clusters.
    2. Go to the cluster that you created and click ⋮ > Edit.
    3. Scroll down to Node Operating System. Choose Windows. Note: You will see that the worker role is the only available role.
    4. Copy the command displayed on screen to your clipboard.
    5. Log in to your Windows host using your preferred tool, such as Microsoft Remote Desktop. Run the command copied to your clipboard in the Command Prompt (CMD).
    6. From Rancher, click Save.
    7. Optional: Repeat these instructions if you want to add more Windows nodes to your cluster.

    Result: The Worker role is installed on your Windows host, and the node registers with Rancher. It may take a few minutes for the node to be registered in your cluster. You now have a Windows Kubernetes cluster.

    Optional Next Steps​

    After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

    • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
    • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through the Rancher server. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

    Configuration for Storage Classes in Azure

    If you are using Azure VMs for your nodes, you can use Azure files as a StorageClass for the cluster. For details, refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/user-settings.html b/v2.5/pages-for-subheaders/user-settings.html index f0441522b11..8fa3ed49730 100644 --- a/v2.5/pages-for-subheaders/user-settings.html +++ b/v2.5/pages-for-subheaders/user-settings.html @@ -5,13 +5,13 @@ User Settings | Rancher Manager - +
    Version: v2.5

    User Settings

    Within Rancher, each user has a number of settings associated with their login: personal preferences, API keys, etc. You can configure these settings by choosing from the User Settings menu. You can open this menu by clicking your avatar, located within the main menu.

    User Settings Menu

    The available user settings are:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/vsphere-cloud-provider.html b/v2.5/pages-for-subheaders/vsphere-cloud-provider.html index 597935f88ab..1cdf09b6f7b 100644 --- a/v2.5/pages-for-subheaders/vsphere-cloud-provider.html +++ b/v2.5/pages-for-subheaders/vsphere-cloud-provider.html @@ -5,13 +5,13 @@ Setting up the vSphere Cloud Provider | Rancher Manager - +
    Version: v2.5

    Setting up the vSphere Cloud Provider

    In this section, you'll learn how to set up a vSphere cloud provider for a Rancher managed RKE Kubernetes cluster in vSphere.

    In-tree Cloud Provider

    To use the in-tree vSphere cloud provider, you will need to use an RKE configuration option. For details, refer to this page.

    Out-of-tree Cloud Provider

    Available as of v2.5+

    To set up the out-of-tree vSphere cloud provider, you will need to install Helm charts from the Rancher marketplace. For details, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/vsphere.html b/v2.5/pages-for-subheaders/vsphere.html index cff87f9185c..8b4f157dce2 100644 --- a/v2.5/pages-for-subheaders/vsphere.html +++ b/v2.5/pages-for-subheaders/vsphere.html @@ -5,13 +5,13 @@ Creating a vSphere Cluster | Rancher Manager - +
    Version: v2.5

    Creating a vSphere Cluster

    By using Rancher with vSphere, you can bring cloud operations on-premises.

    Rancher can provision nodes in vSphere and install Kubernetes on them. When creating a Kubernetes cluster in vSphere, Rancher first provisions the specified number of virtual machines by communicating with the vCenter API. Then it installs Kubernetes on top of them.

    A vSphere cluster may consist of multiple groups of VMs with distinct properties, such as the amount of memory or the number of vCPUs. This grouping allows for fine-grained control over the sizing of nodes for each Kubernetes role.

    vSphere Enhancements in Rancher v2.3

    The vSphere node templates have been updated, allowing you to bring cloud operations on-premises with the following enhancements:

    Self-healing Node Pools​

    One of the biggest advantages of provisioning vSphere nodes with Rancher is that it allows you to take advantage of Rancher's self-healing node pools, also called the node auto-replace feature, in your on-premises clusters. Self-healing node pools are designed to help you replace worker nodes for stateless applications. When Rancher provisions nodes from a node template, Rancher can automatically replace unreachable nodes.

    Important: It is not recommended to enable node auto-replace on a node pool of master nodes or nodes with persistent volumes attached, because VMs are treated ephemerally. When a node in a node pool loses connectivity with the cluster, its persistent volumes are destroyed, resulting in data loss for stateful applications.

    Dynamically Populated Options for Instances and Scheduling​

    Node templates for vSphere have been updated so that when you create a node template with your vSphere credentials, the template is automatically populated with the same options for provisioning VMs that you have access to in the vSphere console.

    For the fields to be populated, your setup needs to fulfill the prerequisites.

    More Supported Operating Systems​

    You can provision VMs with any operating system that supports cloud-init. Only YAML format is supported for the cloud config.

    Video Walkthrough of v2.3.3 Node Template Features​

    In this YouTube video, we demonstrate how to set up a node template with the new features designed to help you bring cloud operations to on-premises clusters.

    Creating a vSphere Cluster​

    In this section, you'll learn how to use Rancher to install an RKE Kubernetes cluster in vSphere.

    Provisioning Storage​

    For an example of how to provision storage in vSphere using Rancher, refer to this section. In order to dynamically provision storage in vSphere, the vSphere provider must be enabled.

    Enabling the vSphere Cloud Provider​

    When a cloud provider is set up in Rancher, the Rancher server can automatically provision new infrastructure for the cluster, including new nodes or persistent storage devices.

    For details, refer to the section on enabling the vSphere cloud provider.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/pages-for-subheaders/workloads-and-pods.html b/v2.5/pages-for-subheaders/workloads-and-pods.html index 9a6ef11273b..d20db67915b 100644 --- a/v2.5/pages-for-subheaders/workloads-and-pods.html +++ b/v2.5/pages-for-subheaders/workloads-and-pods.html @@ -5,14 +5,14 @@ Kubernetes Workloads and Pods | Rancher Manager - +
    Version: v2.5

    Kubernetes Workloads and Pods

    You can build any complex containerized application in Kubernetes using two basic constructs: pods and workloads. Once you build an application, you can expose it for access either within the same cluster or on the Internet using a third construct: services.

    Pods​

    Pods are one or more containers that share network namespaces and storage volumes. Most pods have only one container. Therefore when we discuss pods, the term is often synonymous with containers. You scale pods the same way you scale containers—by having multiple instances of the same pod that implement a service. Usually pods get scaled and managed by the workload.

    Workloads​

    Workloads are objects that set deployment rules for pods. Based on these rules, Kubernetes performs the deployment and updates the workload with the current state of the application. Workloads let you define the rules for application scheduling, scaling, and upgrade.

    Workload Types​

    Kubernetes divides workloads into different types. The most popular types supported by Kubernetes are:

    • Deployments

      Deployments are best used for stateless applications (i.e., when you don't have to maintain the workload's state). Pods managed by deployment workloads are treated as independent and disposable. If a pod encounters disruption, Kubernetes removes it and then recreates it. An example application would be an Nginx web server.

    • StatefulSets

      StatefulSets, in contrast to deployments, are best used when your application needs to maintain its identity and store data. An application would be something like Zookeeper—an application that requires a database for storage.

    • DaemonSets

      Daemonsets ensures that every node in the cluster runs a copy of pod. For use cases where you're collecting logs or monitoring node performance, this daemon-like workload works best.

    • Jobs

      Jobs launch one or more pods and ensure that a specified number of them successfully terminate. Jobs are best used to run a finite task to completion as opposed to managing an ongoing desired application state.

    • CronJobs

      CronJobs are similar to jobs. CronJobs, however, runs to completion on a cron-based schedule.

    Services​

    In many use cases, a workload has to be either:

    • Accessed by other workloads in the cluster.
    • Exposed to the outside world.

    You can achieve these goals by creating a Service. Services are mapped to the underlying workload's pods using a selector/label approach (view the code samples). Rancher UI simplifies this mapping process by automatically creating a service along with the workload, using the service port and type that you select.

    Service Types​

    There are several types of services available in Rancher. The descriptions below are sourced from the Kubernetes Documentation.

    • ClusterIP

      Exposes the service on a cluster-internal IP. Choosing this value makes the service only reachable from within the cluster. This is the default ServiceType.

    • NodePort

      Exposes the service on each Node’s IP at a static port (the NodePort). A ClusterIP service, to which the NodePort service will route, is automatically created. You’ll be able to contact the NodePort service, from outside the cluster, by requesting <NodeIP>:<NodePort>.

    • LoadBalancer

      Exposes the service externally using a cloud provider’s load balancer. NodePort and ClusterIP services, to which the external load balancer will route, are automatically created.

    Workload Options​

    This section of the documentation contains instructions for deploying workloads and using workload options.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides.html b/v2.5/reference-guides.html index 5f6d7dab9c3..70831d0575e 100644 --- a/v2.5/reference-guides.html +++ b/v2.5/reference-guides.html @@ -5,13 +5,13 @@ Reference Guides | Rancher Manager - +
    Version: v2.5

    Reference Guides

    Reference guides are technical descriptions of processes or products that users can study. Reference guides are designed to be "information-oriented" and their primary function is to describe.

    These docs may also include some usage steps in the course of description; however, their purpose is not to explain concepts nor to outline steps to achieve tasks.

    The users who utilize reference guides are knowledgeable with the Rancher product as well as how to use it. They will benefit from detailed descriptions of something to be used when needing to refer to specifics of usage.

    Good examples of Rancher reference guides would be the Rancher Manager architecture and cluster configuration guides.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/about-the-api/api-tokens.html b/v2.5/reference-guides/about-the-api/api-tokens.html index cc2379246f2..d366622b453 100644 --- a/v2.5/reference-guides/about-the-api/api-tokens.html +++ b/v2.5/reference-guides/about-the-api/api-tokens.html @@ -5,14 +5,14 @@ API Tokens | Rancher Manager - +
    Version: v2.5

    API Tokens

    By default, some cluster-level API tokens are generated with infinite time-to-live (ttl=0). In other words, API tokens with ttl=0 never expire unless you invalidate them. Tokens are not invalidated by changing a password.

    You can deactivate API tokens by deleting them or by deactivating the user account.

    Deleting tokens​

    To delete a token,

    1. Go to the list of all tokens in the Rancher API view at https://<Rancher-Server-IP>/v3/tokens.

    2. Access the token you want to delete by its ID. For example, https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt

    3. Click Delete.

    Here is the complete list of tokens that are generated with ttl=0:

    TokenDescription
    kubeconfig-*Kubeconfig token
    kubectl-shell-*Access to kubectl shell in the browser
    agent-*Token for agent deployment
    compose-token-*Token for compose
    helm-token-*Token for Helm chart deployment
    *-pipeline*Pipeline token for project
    telemetry-*Telemetry token
    drain-node-*Token for drain (we use kubectl for drain because there is no native Kubernetes API)

    Setting TTL on Kubeconfig Tokens​

    Admins can set a global TTL on Kubeconfig tokens. Once the token expires the kubectl command will require the user to authenticate to Rancher.

    1. Disable the kubeconfig-generate-token setting in the Rancher API view at https://<Rancher-Server-IP/v3/settings/kubeconfig-generate-token. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. The kubeconfig file will now provide a command to login to Rancher.

    2. Edit the setting and set the value to false.

    3. Go to setting kubeconfig-token-ttl-minutes in the Rancher API view at https://<Rancher-Server-IP/v3/settings/kubeconfig-token-ttl-minutes. By default, kubeconfig-token-ttl-minutes is 960 (16 hours).

    4. Edit the setting and set the value to desired duration in minutes. Note: This value cannot exceed max-ttl of API tokens.(https://<Rancher-Server-IP/v3/settings/auth-token-max-ttl-minutes). auth-token-max-ttl-minutes is set to 1440 (24 hours) by default. auth-token-max-ttl-minutes would default to 0 allowing tokens to never expire.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html b/v2.5/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html index 7bb7f3a7c7a..3243601a13c 100644 --- a/v2.5/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html +++ b/v2.5/reference-guides/amazon-eks-permissions/minimum-eks-permissions.html @@ -5,13 +5,13 @@ Minimum EKS Permissions | Rancher Manager - +
    Version: v2.5

    Minimum EKS Permissions

    Documented here is a minimum set of permissions necessary to use all functionality of the EKS driver in Rancher. Additional permissions are required for Rancher to provision the Service Role and VPC resources. Optionally these resources can be created before the cluster creation and will be selectable when defining the cluster configuration.

    ResourceDescription
    Service RoleThe service role provides Kubernetes the permissions it requires to manage resources on your behalf. Rancher can create the service role with the following Service Role Permissions.
    VPCProvides isolated network resources utilised by EKS and worker nodes. Rancher can create the VPC resources with the following VPC Permissions.

    Resource targeting uses * as the ARN of many of the resources created cannot be known before creating the EKS cluster in Rancher.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "EC2Permisssions",
                "Effect": "Allow",
                "Action": [
                    "ec2:RunInstances",
                    "ec2:RevokeSecurityGroupIngress",
                    "ec2:RevokeSecurityGroupEgress",
                    "ec2:DescribeRegions",
                    "ec2:DescribeVpcs",
                    "ec2:DescribeTags",
                    "ec2:DescribeSubnets",
                    "ec2:DescribeSecurityGroups",
                    "ec2:DescribeRouteTables",
                    "ec2:DescribeLaunchTemplateVersions",
                    "ec2:DescribeLaunchTemplates",
                    "ec2:DescribeKeyPairs",
                    "ec2:DescribeInternetGateways",
                    "ec2:DescribeImages",
                    "ec2:DescribeAvailabilityZones",
                    "ec2:DescribeAccountAttributes",
                    "ec2:DeleteTags",
                    "ec2:DeleteSecurityGroup",
                    "ec2:DeleteKeyPair",
                    "ec2:CreateTags",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateLaunchTemplateVersion",
                    "ec2:CreateLaunchTemplate",
                    "ec2:CreateKeyPair",
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:AuthorizeSecurityGroupEgress"
                ],
                "Resource": "*"
            },
            {
                "Sid": "CloudFormationPermisssions",
                "Effect": "Allow",
                "Action": [
                    "cloudformation:ListStacks",
                    "cloudformation:ListStackResources",
                    "cloudformation:DescribeStacks",
                    "cloudformation:DescribeStackResources",
                    "cloudformation:DescribeStackResource",
                    "cloudformation:DeleteStack",
                    "cloudformation:CreateStackSet",
                    "cloudformation:CreateStack"
                ],
                "Resource": "*"
            },
            {
                "Sid": "IAMPermissions",
                "Effect": "Allow",
                "Action": [
                    "iam:PassRole",
                    "iam:ListRoles",
                    "iam:ListRoleTags",
                    "iam:ListInstanceProfilesForRole",
                    "iam:ListInstanceProfiles",
                    "iam:ListAttachedRolePolicies",
                    "iam:GetRole",
                    "iam:GetInstanceProfile",
                    "iam:DetachRolePolicy",
                    "iam:DeleteRole",
                    "iam:CreateRole",
                    "iam:AttachRolePolicy"
                ],
                "Resource": "*"
            },
            {
                "Sid": "KMSPermisssions",
                "Effect": "Allow",
                "Action": "kms:ListKeys",
                "Resource": "*"
            },
            {
                "Sid": "EKSPermisssions",
                "Effect": "Allow",
                "Action": [
                    "eks:UpdateNodegroupVersion",
                    "eks:UpdateNodegroupConfig",
                    "eks:UpdateClusterVersion",
                    "eks:UpdateClusterConfig",
                    "eks:UntagResource",
                    "eks:TagResource",
                    "eks:ListUpdates",
                    "eks:ListTagsForResource",
                    "eks:ListNodegroups",
                    "eks:ListFargateProfiles",
                    "eks:ListClusters",
                    "eks:DescribeUpdate",
                    "eks:DescribeNodegroup",
                    "eks:DescribeFargateProfile",
                    "eks:DescribeCluster",
                    "eks:DeleteNodegroup",
                    "eks:DeleteFargateProfile",
                    "eks:DeleteCluster",
                    "eks:CreateNodegroup",
                    "eks:CreateFargateProfile",
                    "eks:CreateCluster"
                ],
                "Resource": "*"
            }
        ]
    }

    Service Role Permissions​

    Permissions required for Rancher to create service role on users behalf during the EKS cluster creation process.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "IAMPermisssions",
          "Effect": "Allow",
          "Action": [
            "iam:AddRoleToInstanceProfile",
            "iam:AttachRolePolicy",
            "iam:CreateInstanceProfile",
            "iam:CreateRole",
            "iam:CreateServiceLinkedRole",
            "iam:DeleteInstanceProfile",
            "iam:DeleteRole",
            "iam:DetachRolePolicy",
            "iam:GetInstanceProfile",
            "iam:GetRole",
            "iam:ListAttachedRolePolicies",
            "iam:ListInstanceProfiles",
            "iam:ListInstanceProfilesForRole",
            "iam:ListRoles",
            "iam:ListRoleTags",
            "iam:PassRole",
            "iam:RemoveRoleFromInstanceProfile"
          ],
          "Resource": "*"
        }
      ]
    }

    When an EKS cluster is created, Rancher will create a service role with the following trust policy:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "sts:AssumeRole",
          "Principal": {
            "Service": "eks.amazonaws.com"
          },
          "Effect": "Allow",
          "Sid": ""
        }
      ]
    }

    This role will also have two role policy attachments with the following policies ARNs:

    arn:aws:iam::aws:policy/AmazonEKSClusterPolicy
    arn:aws:iam::aws:policy/AmazonEKSServicePolicy

    VPC Permissions​

    Permissions required for Rancher to create VPC and associated resources.

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "VPCPermissions",
          "Effect": "Allow",
          "Action": [
            "ec2:ReplaceRoute",
            "ec2:ModifyVpcAttribute",
            "ec2:ModifySubnetAttribute",
            "ec2:DisassociateRouteTable",
            "ec2:DetachInternetGateway",
            "ec2:DescribeVpcs",
            "ec2:DeleteVpc",
            "ec2:DeleteTags",
            "ec2:DeleteSubnet",
            "ec2:DeleteRouteTable",
            "ec2:DeleteRoute",
            "ec2:DeleteInternetGateway",
            "ec2:CreateVpc",
            "ec2:CreateSubnet",
            "ec2:CreateSecurityGroup",
            "ec2:CreateRouteTable",
            "ec2:CreateRoute",
            "ec2:CreateInternetGateway",
            "ec2:AttachInternetGateway",
            "ec2:AssociateRouteTable"
          ],
          "Resource": "*"
        }
      ]
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/backup-restore-configuration/backup-configuration.html b/v2.5/reference-guides/backup-restore-configuration/backup-configuration.html index 7de9de30859..014c253d8d2 100644 --- a/v2.5/reference-guides/backup-restore-configuration/backup-configuration.html +++ b/v2.5/reference-guides/backup-restore-configuration/backup-configuration.html @@ -5,14 +5,14 @@ Backup Configuration | Rancher Manager - +
    Version: v2.5

    Backup Configuration

    The Backup Create page lets you configure a schedule, enable encryption and specify the storage location for your backups.

    Schedule​

    Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting Recurring Backups lets you configure following two fields:

    • Schedule: This field accepts
      • Standard cron expressions, such as "0 * * * *"
      • Descriptors, such as "@midnight" or "@every 1h30m"
    • Retention Count: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10.

    YAML Directive NameDescription
    scheduleProvide the cron string for scheduling recurring backups.
    retentionCountProvide the number of backup files to be retained.

    Encryption​

    The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if encryption At rest is enabled, even the encrypted objects gathered by the backup will be in plaintext.

    To avoid storing them in plaintext, you can use the same encryptionConfig file that was used for at-rest encryption, to encrypt certain resources in your backup.

    Important: You must save the encryptionConfig file, because it won’t be saved by the rancher-backup operator. The same encryptionFile needs to be used when performing a restore.

    The operator consumes this encryptionConfig as a Kubernetes Secret, and the Secret must be in the operator’s namespace. Rancher installs the rancher-backup operator in the cattle-resources-system namespace, so create this encryptionConfig secret in that namespace.

    For the EncryptionConfiguration, you can use the sample file provided in the Kubernetes documentation.

    To create the Secret, the encryption configuration file must be named encryption-provider-config.yaml, and the --from-file flag must be used to create this secret.

    Save the EncryptionConfiguration in a file called encryption-provider-config.yaml and run this command:

    kubectl create secret generic encryptionconfig \
      --from-file=./encryption-provider-config.yaml \
      -n cattle-resources-system

    This will ensure that the secret contains a key named encryption-provider-config.yaml, and the operator will use this key to get the encryption configuration.

    The Encryption Config Secret dropdown will filter out and list only those Secrets that have this exact key

    In the example command above, the name encryptionconfig can be changed to anything.

    YAML Directive NameDescription
    encryptionConfigSecretNameProvide the name of the Secret from cattle-resources-system namespace, that contains the encryption config file.

    Storage Location​

    If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the rancher-backup operator.

    Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup.

    S3​

    The S3 storage location contains the following configuration fields:

    1. Credential Secret (optional): If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section. The Credential Secret dropdown lists the secrets in all namespaces.
    2. Bucket Name: The name of the S3 bucket where backup files will be stored.
    3. Region (optional): The AWS region where the S3 bucket is located. This field isn't needed for configuring MinIO.
    4. Folder (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    5. Endpoint: The endpoint that is used to access S3 in the region of your bucket.
    6. Endpoint CA (optional): This should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    7. Skip TLS Verifications (optional): Set to true if you are not using TLS.
    YAML Directive NameDescriptionRequired
    credentialSecretNameIf you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives accessKey and secretKey. It can be in any namespace as long as you provide that namespace in credentialSecretNamespace. An example secret is here. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    credentialSecretNamespaceThe namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in this section.
    bucketNameThe name of the S3 bucket where backup files will be stored.✓
    folderThe name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., rancher/cluster1) are not supported.
    regionThe AWS region where the S3 bucket is located.✓
    endpointThe endpoint that is used to access S3 in the region of your bucket.✓
    endpointCAThis should be the Base64 encoded CA cert. For an example, refer to the example S3 compatible configuration.
    insecureTLSSkipVerifySet to true if you are not using TLS.

    Example S3 Storage Configuration​

    s3:
      credentialSecretName: s3-creds
      credentialSecretNamespace: default
      bucketName: rancher-backups
      folder: rancher
      region: us-west-2
      endpoint: s3.us-west-2.amazonaws.com

    Example MinIO Configuration​

    s3:
      credentialSecretName: minio-creds
      bucketName: rancherbackups
      endpoint: minio.35.202.130.254.sslip.io
      endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t

    Example credentialSecret​

    apiVersion: v1
    kind: Secret
    metadata:
      name: creds
    type: Opaque
    data:
      accessKey: <Enter your base64-encoded access key>
      secretKey: <Enter your base64-encoded secret key>

    IAM Permissions for EC2 Nodes to Access S3​

    There are two ways to set up the rancher-backup operator to use S3 as the backup storage location.

    One way is to configure the credentialSecretName in the Backup custom resource, which refers to AWS credentials that have access to S3.

    If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3.

    To allow a node to access S3, follow the instructions in the AWS documentation to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the Resource with your bucket name:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket"
          ],
         "Resource": [
            "arn:aws:s3:::rancher-backups"
          ]
        },
        {
          "Effect": "Allow",
          "Action": [
            "s3:PutObject",
            "s3:GetObject",
            "s3:DeleteObject",
            "s3:PutObjectAcl"
          ],
          "Resource": [
             "arn:aws:s3:::rancher-backups/*"
          ]
        }
      ]
    }

    After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the credentialSecretName directive can be left empty in the Backup custom resource.

    Examples​

    For example Backup custom resources, refer to this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/backup-restore-configuration/examples.html b/v2.5/reference-guides/backup-restore-configuration/examples.html index 03cacdb93dd..d440d3e2e9f 100644 --- a/v2.5/reference-guides/backup-restore-configuration/examples.html +++ b/v2.5/reference-guides/backup-restore-configuration/examples.html @@ -5,13 +5,13 @@ Examples | Rancher Manager - +
    Version: v2.5

    Examples

    This section contains examples of Backup and Restore custom resources.

    The default backup storage location is configured when the rancher-backup operator is installed or upgraded.

    Encrypted backups can only be restored if the Restore custom resource uses the same encryption configuration secret that was used to create the backup.

    Backup​

    This section contains example Backup custom resources.

    Backup in the Default Location with Encryption​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-location-encrypted-backup
    spec:
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Recurring Backup in the Default Location​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-location-recurring-backup
    spec:
      resourceSetName: rancher-resource-set
      schedule: "@every 1h"
      retentionCount: 10

    Encrypted Recurring Backup in the Default Location​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: default-enc-recurring-backup
    spec:
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig
      schedule: "@every 1h"
      retentionCount: 3

    Encrypted Backup in Minio​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: minio-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: minio-creds
          credentialSecretNamespace: default
          bucketName: rancherbackups
          endpoint: minio.sslip.io
          endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Backup in S3 Using AWS Credential Secret​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Recurring Backup in S3 Using AWS Credential Secret​

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-recurring-backup
    spec:
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig
      schedule: "@every 1h"
      retentionCount: 10

    Backup from EC2 Nodes with IAM Permission to Access S3​

    This example shows that the AWS credential secret does not have to be provided to create a backup if the nodes running rancher-backup have these permissions for access to S3.

    apiVersion: resources.cattle.io/v1
    kind: Backup
    metadata:
      name: s3-iam-backup
    spec:
      storageLocation:
        s3:
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      resourceSetName: rancher-resource-set
      encryptionConfigSecretName: encryptionconfig

    Restore​

    This section contains example Restore custom resources.

    Restore Using the Default Backup File Location​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-default
    spec:
      backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz
    #  encryptionConfigSecretName: test-encryptionconfig

    Restore for Rancher Migration​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-migration
    spec:
      backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
      prune: false
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com

    Restore from Encrypted Backup​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-encrypted
    spec:
      backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz
      encryptionConfigSecretName: encryptionconfig

    Restore an Encrypted Backup from Minio​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-minio
    spec:
      backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz
      storageLocation:
        s3:
          credentialSecretName: minio-creds
          credentialSecretNamespace: default
          bucketName: rancherbackups
          endpoint: minio.sslip.io
          endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t
      encryptionConfigSecretName: test-encryptionconfig

    Restore from Backup Using an AWS Credential Secret to Access S3​

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-s3-demo
    spec:
      backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc
      storageLocation:
        s3:
          credentialSecretName: s3-creds
          credentialSecretNamespace: default
          bucketName: rancher-backups
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      encryptionConfigSecretName: test-encryptionconfig

    Restore from EC2 Nodes with IAM Permissions to Access S3​

    This example shows that the AWS credential secret does not have to be provided to restore from backup if the nodes running rancher-backup have these permissions for access to S3.

    apiVersion: resources.cattle.io/v1
    kind: Restore
    metadata:
      name: restore-s3-demo
    spec:
      backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz
      storageLocation:
        s3:
          bucketName: rajashree-backup-test
          folder: ecm1
          region: us-west-2
          endpoint: s3.us-west-2.amazonaws.com
      encryptionConfigSecretName: test-encryptionconfig

    Example Credential Secret for Storing Backups in S3

    apiVersion: v1
    kind: Secret
    metadata:
      name: creds
    type: Opaque
    data:
      accessKey: <Enter your base64-encoded access key>
      secretKey: <Enter your base64-encoded secret key>

    Example EncryptionConfiguration

    apiVersion: apiserver.config.k8s.io/v1
    kind: EncryptionConfiguration
    resources:
      - resources:
          - secrets
        providers:
          - aesgcm:
              keys:
                - name: key1
                  secret: c2VjcmV0IGlzIHNlY3VyZQ==
                - name: key2
                  secret: dGhpcyBpcyBwYXNzd29yZA==
          - aescbc:
              keys:
                - name: key1
                  secret: c2VjcmV0IGlzIHNlY3VyZQ==
                - name: key2
                  secret: dGhpcyBpcyBwYXNzd29yZA==
          - secretbox:
              keys:
                - name: key1
                  secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/backup-restore-configuration/restore-configuration.html b/v2.5/reference-guides/backup-restore-configuration/restore-configuration.html index 18853889187..f613a3b2fc1 100644 --- a/v2.5/reference-guides/backup-restore-configuration/restore-configuration.html +++ b/v2.5/reference-guides/backup-restore-configuration/restore-configuration.html @@ -5,14 +5,14 @@ Restore Configuration | Rancher Manager - +
    Version: v2.5

    Restore Configuration

    The Restore Create page lets you provide details of the backup to restore from

    Backup Source​

    Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details

    An existing backup config​

    Selecting this option will populate the Target Backup dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the Backup Filename field for you, and will also pass the backup source information from the selected Backup to the operator.

    If the Backup custom resource does not exist in the cluster, you need to get the exact filename and provide the backup source details with the default storage target or an S3-compatible object store.

    The default storage target​

    Select this option if you are restoring from a backup file that exists in the default storage location configured at the operator-level. The operator-level configuration is the storage location that was configured when the rancher-backup operator was installed or upgraded. Provide the exact filename in the Backup Filename field.

    An S3-compatible object store​

    Select this option if no default storage location is configured at the operator-level, OR if the backup file exists in a different S3 bucket than the one configured as the default storage location. Provide the exact filename in the Backup Filename field. Refer to this section for exact steps on getting the backup filename from s3. Fill in all the details for the S3 compatible object store. Its fields are exactly same as ones for the backup.StorageLocation configuration in the Backup custom resource.

    Encryption​

    If the backup was created with encryption enabled, its file will have .enc suffix. Choosing such a Backup, or providing a backup filename with .enc suffix will display another dropdown named Encryption Config Secret.

    The Secret selected from this dropdown must have the same contents as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail

    The Encryption Config Secret dropdown will filter out and list only those Secrets that have this exact key

    YAML Directive NameDescription
    encryptionConfigSecretNameProvide the name of the Secret from cattle-resources-system namespace, that contains the encryption config file.

    Important This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail.

    Prune During Restore​

    • Prune: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the Prune flag is enabled. Prune is enabled by default and it is recommended to keep it enabled.
    • Delete Timeout: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.
    YAML Directive NameDescription
    pruneDelete the resources managed by Rancher that are not present in the backup (Recommended).
    deleteTimeoutSecondsAmount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.

    Getting the Backup Filename from S3​

    This is the name of the backup file that the rancher-backup operator will use to perform the restore.

    To obtain this file name from S3, go to your S3 bucket (and folder if it was specified while performing backup).

    Copy the filename and store it in your Restore custom resource. So assuming the name of your backup file is backupfile,

    • If your bucket name is s3bucket and no folder was specified, then the backupFilename to use will be backupfile.
    • If your bucket name is s3bucket and the base folder iss3folder, the backupFilename to use is only backupfile .
    • If there is a subfolder inside s3Folder called s3sub, and that has your backup file, then the backupFilename to use is s3sub/backupfile.
    YAML Directive NameDescription
    backupFilenameThis is the name of the backup file that the rancher-backup operator will use to perform the restore.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/backup-restore-configuration/storage-configuration.html b/v2.5/reference-guides/backup-restore-configuration/storage-configuration.html index d46846130c4..58305acd7a0 100644 --- a/v2.5/reference-guides/backup-restore-configuration/storage-configuration.html +++ b/v2.5/reference-guides/backup-restore-configuration/storage-configuration.html @@ -5,7 +5,7 @@ Backup Storage Location Configuration | Rancher Manager - + @@ -14,7 +14,7 @@ It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the rancher-backup chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted. If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it.

    Existing Persistent Volume​

    Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to this section.

    Important It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the rancher-backup chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.

    Example values.yaml for the rancher-backup Helm Chart​

    The documented values.yaml file that can be used to configure rancher-backup operator when the Helm CLI is used can be found in the backup-restore-operator repository.

    For more information about values.yaml files and configuring Helm charts during installation, refer to the Helm documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html b/v2.5/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html index 5b6c5c9e1e8..cf05db66eee 100644 --- a/v2.5/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html +++ b/v2.5/reference-guides/best-practices/rancher-managed-clusters/logging-best-practices.html @@ -5,13 +5,13 @@ Logging Best Practices | Rancher Manager - +
    Version: v2.5

    Logging Best Practices

    In this guide, we recommend best practices for cluster-level logging and application logging.

    Changes in Logging in Rancher v2.5​

    Before Rancher v2.5, logging in Rancher has historically been a pretty static integration. There were a fixed list of aggregators to choose from (ElasticSearch, Splunk, Kafka, Fluentd and Syslog), and only two configuration points to choose (Cluster-level and Project-level).

    Logging in 2.5 has been completely overhauled to provide a more flexible experience for log aggregation. With the new logging feature, administrators and users alike can deploy logging that meets fine-grained collection criteria while offering a wider array of destinations and configuration options.

    "Under the hood", Rancher logging uses the Banzai Cloud logging operator. We provide manageability of this operator (and its resources), and tie that experience in with managing your Rancher clusters.

    Cluster-level Logging​

    Cluster-wide Scraping​

    For some users, it is desirable to scrape logs from every container running in the cluster. This usually coincides with your security team's request (or requirement) to collect all logs from all points of execution.

    In this scenario, it is recommended to create at least two ClusterOutput objects - one for your security team (if you have that requirement), and one for yourselves, the cluster administrators. When creating these objects take care to choose an output endpoint that can handle the significant log traffic coming from the entire cluster. Also make sure to choose an appropriate index to receive all these logs.

    Once you have created these ClusterOutput objects, create a ClusterFlow to collect all the logs. Do not define any Include or Exclude rules on this flow. This will ensure that all logs from across the cluster are collected. If you have two ClusterOutputs, make sure to send logs to both of them.

    Kubernetes Components​

    ClusterFlows have the ability to collect logs from all containers on all hosts in the Kubernetes cluster. This works well in cases where those containers are part of a Kubernetes pod; however, RKE containers exist outside of the scope of Kubernetes.

    Currently (as of v2.5.1) the logs from RKE containers are collected, but are not able to easily be filtered. This is because those logs do not contain information as to the source container (e.g. etcd or kube-apiserver).

    A future release of Rancher will include the source container name which will enable filtering of these component logs. Once that change is made, you will be able to customize a ClusterFlow to retrieve only the Kubernetes component logs, and direct them to an appropriate output.

    Application Logging​

    Best practice not only in Kubernetes but in all container-based applications is to direct application logs to stdout/stderr. The container runtime will then trap these logs and do something with them - typically writing them to a file. Depending on the container runtime (and its configuration), these logs can end up in any number of locations.

    In the case of writing the logs to a file, Kubernetes helps by creating a /var/log/containers directory on each host. This directory symlinks the log files to their actual destination (which can differ based on configuration or container runtime).

    Rancher logging will read all log entries in /var/log/containers, ensuring that all log entries from all containers (assuming a default configuration) will have the opportunity to be collected and processed.

    Specific Log Files​

    Log collection only retrieves stdout/stderr logs from pods in Kubernetes. But what if we want to collect logs from other files that are generated by applications? Here, a log streaming sidecar (or two) may come in handy.

    The goal of setting up a streaming sidecar is to take log files that are written to disk, and have their contents streamed to stdout. This way, the Banzai Logging Operator can pick up those logs and send them to your desired output.

    To set this up, edit your workload resource (e.g. Deployment) and add the following sidecar definition:

    ...
    containers:
    - args:
      - -F
      - /path/to/your/log/file.log
      command:
      - tail
      image: busybox
      name: stream-log-file-[name]
      volumeMounts:
      - mountPath: /path/to/your/log
        name: mounted-log
    ...

    This will add a container to your workload definition that will now stream the contents of (in this example) /path/to/your/log/file.log to stdout.

    This log stream is then automatically collected according to any Flows or ClusterFlows you have setup. You may also wish to consider creating a Flow specifically for this log file by targeting the name of the container. See example:

    ...
    spec:
      match:
      - select:
          container_names:
          - stream-log-file-name
    ...

    General Best Practices​

    • Where possible, output structured log entries (e.g. syslog, JSON). This makes handling of the log entry easier as there are already parsers written for these formats.
    • Try to provide the name of the application that is creating the log entry, in the entry itself. This can make troubleshooting easier as Kubernetes objects do not always carry the name of the application as the object name. For instance, a pod ID may be something like myapp-098kjhsdf098sdf98 which does not provide much information about the application running inside the container.
    • Except in the case of collecting all logs cluster-wide, try to scope your Flow and ClusterFlow objects tightly. This makes it easier to troubleshoot when problems arise, and also helps ensure unrelated log entries do not show up in your aggregator. An example of tight scoping would be to constrain a Flow to a single Deployment in a namespace, or perhaps even a single container within a Pod.
    • Keep the log verbosity down except when troubleshooting. High log verbosity poses a number of issues, chief among them being noise: significant events can be drowned out in a sea of DEBUG messages. This is somewhat mitigated with automated alerting and scripting, but highly verbose logging still places an inordinate amount of stress on the logging infrastructure.
    • Where possible, try to provide a transaction or request ID with the log entry. This can make tracing application activity across multiple log sources easier, especially when dealing with distributed applications.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html b/v2.5/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html index bd31cef0702..b200474b350 100644 --- a/v2.5/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html +++ b/v2.5/reference-guides/best-practices/rancher-managed-clusters/monitoring-best-practices.html @@ -5,13 +5,13 @@ Monitoring Best Practices | Rancher Manager - +
    Version: v2.5

    Monitoring Best Practices

    Configuring sensible monitoring and alerting rules is vital for running any production workloads securely and reliably. This is not different when using Kubernetes and Rancher. Fortunately the integrated monitoring and alerting functionality makes this whole process a lot easier.

    The Rancher monitoring documentation describes how you can set up a complete Prometheus and Grafana stack. Out of the box this will scrape monitoring data from all system and Kubernetes components in your cluster and provide sensible dashboards and alerts for them to get started. But for a reliable setup, you also need to monitor your own workloads and adapt Prometheus and Grafana to your own specific use cases and cluster sizes. This document aims to give you best practices for this.

    What to Monitor​

    Kubernetes itself, as well as applications running inside of it, form a distributed system where different components interact with each other. For the whole system and each individual component, you have to ensure performance, availability, reliability and scalability. A good resource with more details and information is Google's free Site Reliability Engineering Book, especially the chapter about Monitoring distributed systems.

    Configuring Prometheus Resource Usage​

    When installing the integrated monitoring stack, Rancher allows to configure several settings that are dependent on the size of your cluster and the workloads running in it. This chapter covers these in more detail.

    Storage and Data Retention​

    The amount of storage needed for Prometheus directly correlates to the amount of time series and labels that you store and the data retention you have configured. It is important to note that Prometheus is not meant to be used as a long-term metrics storage. Data retention time is usually only a couple of days and not weeks or months. The reason for this is that Prometheus does not perform any aggregation on its stored metrics. This is great because aggregation can dilute data, but it also means that the needed storage grows linearly over time without retention.

    One way to calculate the necessary storage is to look at the average size of a storage chunk in Prometheus with this query

    rate(prometheus_tsdb_compaction_chunk_size_bytes_sum[1h]) / rate(prometheus_tsdb_compaction_chunk_samples_sum[1h])

    Next, find out your data ingestion rate per second:

    rate(prometheus_tsdb_head_samples_appended_total[1h])

    and then multiply this with the retention time, adding a few percentage points as buffer:

    average chunk size in bytes * ingestion rate per second * retention time in seconds * 1.1 = necessary storage in bytes

    You can find more information about how to calculate the necessary storage in this blog post.

    You can read more about the Prometheus storage concept in the Prometheus documentation.

    CPU and Memory Requests and Limits​

    In larger Kubernetes clusters Prometheus can consume quite a bit of memory. The amount of memory Prometheus needs directly correlates to the amount of time series and amount of labels it stores and the scrape interval in which these are filled.

    You can find more information about how to calculate the necessary memory in this blog post.

    The amount of necessary CPUs correlate with the amount of queries you are performing.

    Federation and Long-term Storage​

    Prometheus is not meant to store metrics for a long amount of time, but should only be used for short term storage.

    In order to store some, or all metrics for a long time, you can leverage Prometheus' remote read/write capabilities to connect it to storage systems like Thanos, InfluxDB, M3DB, or others. You can find an example setup in this blog post.

    Scraping Custom Workloads​

    While the integrated Rancher Monitoring already scrapes system metrics from a cluster's nodes and system components, the custom workloads that you deploy on Kubernetes should also be scraped for data. For that you can configure Prometheus to do an HTTP request to an endpoint of your applications in a certain interval. These endpoints should then return their metrics in a Prometheus format.

    In general, you want to scrape data from all the workloads running in your cluster so that you can use them for alerts or debugging issues. Often, you recognize that you need some data only when you actually need the metrics during an incident. It is good, if it is already scraped and stored. Since Prometheus is only meant to be a short-term metrics storage, scraping and keeping lots of data is usually not that expensive. If you are using a long-term storage solution with Prometheus, you can then still decide which data you are actually persisting and keeping there.

    About Prometheus Exporters​

    A lot of 3rd party workloads like databases, queues or web-servers either already support exposing metrics in a Prometheus format, or there are so called exporters available that translate between the tool's metrics and the format that Prometheus understands. Usually you can add these exporters as additional sidecar containers to the workload's Pods. A lot of helm charts already include options to deploy the correct exporter. Additionally you can find a curated list of exports by SysDig on promcat.io and on ExporterHub.

    Prometheus support in Programming Languages and Frameworks​

    To get your own custom application metrics into Prometheus, you have to collect and expose these metrics directly from your application's code. Fortunately, there are already libraries and integrations available to help with this for most popular programming languages and frameworks. One example for this is the Prometheus support in the Spring Framework.

    ServiceMonitors and PodMonitors​

    Once all your workloads expose metrics in a Prometheus format, you have to configure Prometheus to scrape it. Under the hood Rancher is using the prometheus-operator. This makes it easy to add additional scraping targets with ServiceMonitors and PodMonitors. A lot of helm charts already include an option to create these monitors directly. You can also find more information in the Rancher documentation.

    Prometheus Push Gateway​

    There are some workloads that are traditionally hard to scrape by Prometheus. Examples for these are short lived workloads like Jobs and CronJobs, or applications that do not allow sharing data between individual handled incoming requests, like PHP applications.

    To still get metrics for these use cases, you can set up prometheus-pushgateways. The CronJob or PHP application would push metric updates to the pushgateway. The pushgateway aggregates and exposes them through an HTTP endpoint, which then can be scraped by Prometheus.

    Prometheus Blackbox Monitor​

    Sometimes it is useful to monitor workloads from the outside. For this, you can use the Prometheus blackbox-exporter which allows probing any kind of endpoint over HTTP, HTTPS, DNS, TCP and ICMP.

    Monitoring in a (Micro)Service Architecture​

    If you have a (micro)service architecture where multiple individual workloads within your cluster are communicating with each other, it is really important to have detailed metrics and traces about this traffic to understand how all these workloads are communicating with each other and where a problem or bottleneck may be.

    Of course you can monitor all this internal traffic in all your workloads and expose these metrics to Prometheus. But this can quickly become quite work intensive. Service Meshes like Istio, which can be installed with a click in Rancher, can do this automatically and provide rich telemetry about the traffic between all services.

    Real User Monitoring​

    Monitoring the availability and performance of all your internal workloads is vitally important to run stable, reliable and fast applications. But these metrics only show you parts of the picture. To get a complete view it is also necessary to know how your end users are actually perceiving it. For this you can look into various Real user monitoring solutions.

    Security Monitoring​

    In addition to monitoring workloads to detect performance, availability or scalability problems, the cluster and the workloads running into it should also be monitored for potential security problems. A good starting point is to frequently run and alert on CIS Scans which check if the cluster is configured according to security best practices.

    For the workloads, you can have a look at Kubernetes and Container security solutions like Falco, Aqua Kubernetes Security, SysDig.

    Setting up Alerts​

    Getting all the metrics into a monitoring systems and visualizing them in dashboards is great, but you also want to be pro-actively alerted if something goes wrong.

    The integrated Rancher monitoring already configures a sensible set of alerts that make sense in any Kubernetes cluster. You should extend these to cover your specific workloads and use cases.

    When setting up alerts, configure them for all the workloads that are critical to the availability of your applications. But also make sure that they are not too noisy. Ideally every alert you are receiving should be because of a problem that needs your attention and needs to be fixed. If you have alerts that are firing all the time but are not that critical, there is a danger that you start ignoring your alerts all together and then miss the real important ones. Less may be more here. Start to focus on the real important metrics first, for example alert if your application is offline. Fix all the problems that start to pop up and then start to create more detailed alerts.

    If an alert starts firing, but there is nothing you can do about it at the moment, it's also fine to silence the alert for a certain amount of time, so that you can look at it later.

    You can find more information on how to set up alerts and notification channels in the Rancher Documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html b/v2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html index 6135bcd1da5..7fe37e1dfc7 100644 --- a/v2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html +++ b/v2.5/reference-guides/best-practices/rancher-managed-clusters/rancher-managed-clusters-in-vsphere.html @@ -5,13 +5,13 @@ Best Practices for Rancher Managed vSphere Clusters | Rancher Manager - +
    Version: v2.5

    Best Practices for Rancher Managed vSphere Clusters

    This guide outlines a reference architecture for provisioning downstream Rancher clusters in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Solution Overview

    Solution Overview

    1. VM Considerations

    Leverage VM Templates to Construct the Environment​

    To facilitate consistency across the deployed Virtual Machines across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customisation options.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across ESXi Hosts​

    Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Downstream Cluster Nodes Across Datastores​

    Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.

    Configure VM's as Appropriate for Kubernetes​

    It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.

    2. Network Considerations

    Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes​

    Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.

    Consistent IP Addressing for VM's​

    Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    3. Storage Considerations

    Leverage SSD Drives for ETCD Nodes​

    ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.

    4. Backups and Disaster Recovery

    Perform Regular Downstream Cluster Backups​

    Kubernetes uses etcd to store all its data - from configuration, state and metadata. Backing this up is crucial in the event of disaster recovery.

    Back up Downstream Node VMs​

    Incorporate the Rancher downstream node VM's within a standard VM backup policy.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html b/v2.5/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html index 4d5e417eb6f..c7f5a893f16 100644 --- a/v2.5/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html +++ b/v2.5/reference-guides/best-practices/rancher-managed-clusters/tips-to-set-up-containers.html @@ -5,13 +5,13 @@ Tips for Setting Up Containers | Rancher Manager - +
    Version: v2.5

    Tips for Setting Up Containers

    Running well-built containers can greatly impact the overall performance and security of your environment.

    Below are a few tips for setting up your containers.

    For a more detailed discussion of security for containers, you can also refer to Rancher's Guide to Container Security.

    Use a Common Container OS​

    When possible, you should try to standardize on a common container base OS.

    Smaller distributions such as Alpine and BusyBox reduce container image size and generally have a smaller attack/vulnerability surface.

    Popular distributions such as Ubuntu, Fedora, and CentOS are more field-tested and offer more functionality.

    Start with a FROM scratch container​

    If your microservice is a standalone static binary, you should use a FROM scratch container.

    The FROM scratch container is an official Docker image that is empty so that you can use it to design minimal images.

    This will have the smallest attack surface and smallest image size.

    Run Container Processes as Unprivileged​

    When possible, use a non-privileged user when running processes within your container. While container runtimes provide isolation, vulnerabilities and attacks are still possible. Inadvertent or accidental host mounts can also be impacted if the container is running as root. For details on configuring a security context for a pod or container, refer to the Kubernetes docs.

    Define Resource Limits​

    Apply CPU and memory limits to your pods. This can help manage the resources on your worker nodes and avoid a malfunctioning microservice from impacting other microservices.

    In standard Kubernetes, you can set resource limits on the namespace level. In Rancher, you can set resource limits on the project level and they will propagate to all the namespaces within the project. For details, refer to the Rancher docs.

    When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. To avoid setting these limits on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    The Kubernetes docs have more information on how resource limits can be set at the container level and the namespace level.

    Define Resource Requirements​

    You should apply CPU and memory requirements to your pods. This is crucial for informing the scheduler which type of compute node your pod needs to be placed on, and ensuring it does not over-provision that node. In Kubernetes, you can set a resource requirement by defining resources.requests in the resource requests field in a pod's container spec. For details, refer to the Kubernetes docs.

    Note: If you set a resource limit for the namespace that the pod is deployed in, and the container doesn't have a specific resource request, the pod will not be allowed to start. To avoid setting these fields on each and every container during workload creation, a default container resource limit can be specified on the namespace.

    It is recommended to define resource requirements on the container level because otherwise, the scheduler makes assumptions that will likely not be helpful to your application when the cluster experiences load.

    Liveness and Readiness Probes​

    Set up liveness and readiness probes for your container. Unless your container completely crashes, Kubernetes will not know it's unhealthy unless you create an endpoint or mechanism that can report container status. Alternatively, make sure your container halts and crashes if unhealthy.

    The Kubernetes docs show how to configure liveness and readiness probes for containers.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html b/v2.5/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html index aca92c28f91..d68227120ed 100644 --- a/v2.5/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html +++ b/v2.5/reference-guides/best-practices/rancher-server/on-premises-rancher-in-vsphere.html @@ -5,13 +5,13 @@ Installing Rancher in a vSphere Environment | Rancher Manager - +
    Version: v2.5

    Installing Rancher in a vSphere Environment

    This guide outlines a reference architecture for installing Rancher on an RKE Kubernetes cluster in a vSphere environment, in addition to standard vSphere best practices as documented by VMware.

    Solution Overview

    Solution Overview

    1. Load Balancer Considerations​

    A load balancer is required to direct traffic to the Rancher workloads residing on the RKE nodes.

    Leverage Fault Tolerance and High Availability​

    Leverage the use of an external (hardware or software) load balancer that has inherit high-availability functionality (F5, NSX-T, Keepalived, etc).

    Back Up Load Balancer Configuration​

    In the event of a Disaster Recovery activity, availability of the Load balancer configuration will expedite the recovery process.

    Configure Health Checks​

    Configure the Load balancer to automatically mark nodes as unavailable if a health check is failed. For example, NGINX can facilitate this with:

    max_fails=3 fail_timeout=5s

    Leverage an External Load Balancer​

    Avoid implementing a software load balancer within the management cluster.

    Secure Access to Rancher​

    Configure appropriate Firewall / ACL rules to only expose access to Rancher

    2. VM Considerations​

    Size the VM's According to Rancher Documentation​

    https://rancher.com/docs/rancher/v2.5/en/installation/requirements/

    Leverage VM Templates to Construct the Environment​

    To facilitate the consistency of Virtual Machines deployed across the environment, consider the use of "Golden Images" in the form of VM templates. Packer can be used to accomplish this, adding greater customization options.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across ESXi Hosts​

    Doing so will ensure node VM's are spread across multiple ESXi hosts - preventing a single point of failure at the host level.

    Leverage DRS Anti-Affinity Rules (Where Possible) to Separate Rancher Cluster Nodes Across Datastores​

    Doing so will ensure node VM's are spread across multiple datastores - preventing a single point of failure at the datastore level.

    Configure VM's as Appropriate for Kubernetes​

    It’s important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double-checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node.

    3. Network Considerations​

    Leverage Low Latency, High Bandwidth Connectivity Between ETCD Nodes​

    Deploy etcd members within a single data center where possible to avoid latency overheads and reduce the likelihood of network partitioning. For most setups, 1Gb connections will suffice. For large clusters, 10Gb connections can reduce the time taken to restore from backup.

    Consistent IP Addressing for VM's​

    Each node used should have a static IP configured. In the case of DHCP, each node should have a DHCP reservation to make sure the node gets the same IP allocated.

    4. Storage Considerations​

    Leverage SSD Drives for ETCD Nodes​

    ETCD is very sensitive to write latency. Therefore, leverage SSD disks where possible.

    5. Backups and Disaster Recovery​

    Perform Regular Management Cluster Backups​

    Rancher stores its data in the ETCD datastore of the Kubernetes cluster it resides on. Like with any Kubernetes cluster, perform frequent, tested backups of this cluster.

    Back up Rancher Cluster Node VMs​

    Incorporate the Rancher management node VM's within a standard VM backup policy.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html b/v2.5/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html index dec370485cb..d7f36edbc3e 100644 --- a/v2.5/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html +++ b/v2.5/reference-guides/best-practices/rancher-server/rancher-deployment-strategy.html @@ -5,13 +5,13 @@ Rancher Deployment Strategy | Rancher Manager - +
    Version: v2.5

    Rancher Deployment Strategy

    There are two recommended deployment strategies for a Rancher server that manages downstream Kubernetes clusters. Each one has its own pros and cons. Read more about which one would fit best for your use case:

    Hub & Spoke Strategy​

    In this deployment scenario, there is a single Rancher control plane managing Kubernetes clusters across the globe. The control plane would be run on a high-availability Kubernetes cluster, and there would be impact due to latencies.

    Pros​

    • Environments could have nodes and network connectivity across regions.
    • Single control plane interface to view/see all regions and environments.
    • Kubernetes does not require Rancher to operate and can tolerate losing connectivity to the Rancher control plane.

    Cons​

    • Subject to network latencies.
    • If the control plane goes out, global provisioning of new services is unavailable until it is restored. However, each Kubernetes cluster can continue to be managed individually.

    Regional Strategy​

    In the regional deployment model a control plane is deployed in close proximity to the compute nodes.

    Pros​

    • Rancher functionality in regions stay operational if a control plane in another region goes down.
    • Network latency is greatly reduced, improving the performance of functionality in Rancher.
    • Upgrades of the Rancher control plane can be done independently per region.

    Cons​

    • Overhead of managing multiple Rancher installations.
    • Visibility across global Kubernetes clusters requires multiple interfaces/panes of glass.
    • Deploying multi-cluster apps in Rancher requires repeating the process for each Rancher server.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html b/v2.5/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html index 7966beb2f90..e562865646a 100644 --- a/v2.5/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html +++ b/v2.5/reference-guides/best-practices/rancher-server/tips-for-running-rancher.html @@ -5,13 +5,13 @@ Tips for Running Rancher | Rancher Manager - +
    Version: v2.5

    Tips for Running Rancher

    This guide is geared toward use cases where Rancher is used to manage downstream Kubernetes clusters. The high-availability setup is intended to prevent losing access to downstream clusters if the Rancher server is not available.

    A high-availability Kubernetes installation, defined as an installation of Rancher on a Kubernetes cluster with at least three nodes, should be used in any production installation of Rancher, as well as any installation deemed "important." Multiple Rancher instances running on multiple nodes ensure high availability that cannot be accomplished with a single node environment.

    If you are installing Rancher in a vSphere environment, refer to the best practices documented here.

    When you set up your high-availability Rancher installation, consider the following:

    Run Rancher on a Separate Cluster​

    Don't run other workloads or microservices in the Kubernetes cluster that Rancher is installed on.

    Make sure nodes are configured correctly for Kubernetes​

    It's important to follow K8s and etcd best practices when deploying your nodes, including disabling swap, double checking you have full network connectivity between all machines in the cluster, using unique hostnames, MAC addresses, and product_uuids for every node, checking that all correct ports are opened, and deploying with ssd backed etcd. More details can be found in the kubernetes docs and etcd's performance op guide.

    When using RKE: Back up the Statefile​

    RKE keeps record of the cluster state in a file called cluster.rkestate. This file is important for the recovery of a cluster and/or the continued maintenance of the cluster through RKE. Because this file contains certificate material, we strongly recommend encrypting this file before backing up. After each run of rke up you should backup the state file.

    Run All Nodes in the Cluster in the Same Datacenter​

    For best performance, run all three of your nodes in the same geographic datacenter. If you are running nodes in the cloud, such as AWS, run each node in a separate Availability Zone. For example, launch node 1 in us-west-2a, node 2 in us-west-2b, and node 3 in us-west-2c.

    Development and Production Environments Should be Similar​

    It's strongly recommended to have a "staging" or "pre-production" environment of the Kubernetes cluster that Rancher runs on. This environment should mirror your production environment as closely as possible in terms of software and hardware configuration.

    Monitor Your Clusters to Plan Capacity​

    The Rancher server's Kubernetes cluster should run within the system and hardware requirements as closely as possible. The more you deviate from the system and hardware requirements, the more risk you take.

    However, metrics-driven capacity planning analysis should be the ultimate guidance for scaling Rancher, because the published requirements take into account a variety of workload types.

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution, and Grafana, which lets you visualize the metrics from Prometheus.

    After you enable monitoring in the cluster, you can set up a notification channel and alerts to let you know if your cluster is approaching its capacity. You can also use the Prometheus and Grafana monitoring framework to establish a baseline for key metrics as you scale.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cli-with-rancher/kubectl-utility.html b/v2.5/reference-guides/cli-with-rancher/kubectl-utility.html index f417f02edd6..b5ad7ce7c70 100644 --- a/v2.5/reference-guides/cli-with-rancher/kubectl-utility.html +++ b/v2.5/reference-guides/cli-with-rancher/kubectl-utility.html @@ -5,14 +5,14 @@ kubectl Utility | Rancher Manager - +
    Version: v2.5

    kubectl

    Interact with Rancher using kubectl.

    kubectl Utility​

    Install the kubectl utility. See install kubectl.

    Configure kubectl by visiting your cluster in the Rancher Web UI, clicking on Kubeconfig, copying contents, and putting them into your ~/.kube/config file.

    Run kubectl cluster-info or kubectl get pods successfully.

    Authentication with kubectl and kubeconfig Tokens with TTL​

    Requirements

    If admins have enforced TTL on kubeconfig tokens, the kubeconfig file requires the Rancher CLI to be present in your PATH when you run kubectl. Otherwise, you’ll see an error like: Unable to connect to the server: getting credentials: exec: exec: "rancher": executable file not found in $PATH.

    This feature enables kubectl to authenticate with the Rancher server and get a new kubeconfig token when required. The following auth providers are currently supported:

    1. Local
    2. Active Directory (LDAP only)
    3. FreeIPA
    4. OpenLDAP
    5. SAML providers: Ping, Okta, ADFS, Keycloak, Shibboleth

    When you first run kubectl, for example, kubectl get pods, it will ask you to pick an auth provider and log in with the Rancher server. The kubeconfig token is cached in the path where you run kubectl under ./.cache/token. This token is valid until it expires, or gets deleted from the Rancher server. Upon expiration, the next kubectl get pods will ask you to log in with the Rancher server again.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cli-with-rancher/rancher-cli.html b/v2.5/reference-guides/cli-with-rancher/rancher-cli.html index 077f8211bd1..b9bcf55c49f 100644 --- a/v2.5/reference-guides/cli-with-rancher/rancher-cli.html +++ b/v2.5/reference-guides/cli-with-rancher/rancher-cli.html @@ -5,13 +5,13 @@ Rancher CLI | Rancher Manager - +
    Version: v2.5

    Rancher CLI

    The Rancher CLI (Command Line Interface) is a unified tool that you can use to interact with Rancher. With this tool, you can operate Rancher using a command line rather than the GUI.

    Download Rancher CLI​

    The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

    1. In the upper left corner, click ☰.
    2. At the bottom, click v2.6.x, where v2.6.x is a hyperlinked text indicating the installed Rancher version.
    3. Under the CLI Downloads section, there are links to download the binaries for Windows, Mac, and Linux. You can also check the releases page for our CLI for direct downloads of the binary.

    Requirements​

    After you download the Rancher CLI, you need to make a few configurations. Rancher CLI requires:

    • Your Rancher Server URL, which is used to connect to Rancher Server.
    • An API Bearer Token, which is used to authenticate with Rancher. For more information about obtaining a Bearer Token, see Creating an API Key.

    CLI Authentication​

    Before you can use Rancher CLI to control your Rancher Server, you must authenticate using an API Bearer Token. Log in using the following command (replace <BEARER_TOKEN> and <SERVER_URL> with your information):

    $ ./rancher login https://<SERVER_URL> --token <BEARER_TOKEN>

    If Rancher Server uses a self-signed certificate, Rancher CLI prompts you to continue with the connection.

    Project Selection​

    Before you can perform any commands, you must select a Rancher project to perform those commands against. To select a project to work on, use the command ./rancher context switch. When you enter this command, a list of available projects displays. Enter a number to choose your project.

    Example: ./rancher context switch Output

    User:rancher-cli-directory user$ ./rancher context switch
    NUMBER    CLUSTER NAME   PROJECT ID              PROJECT NAME
    1         cluster-2      c-7q96s:p-h4tmb         project-2
    2         cluster-2      c-7q96s:project-j6z6d   Default
    3         cluster-1      c-lchzv:p-xbpdt         project-1
    4         cluster-1      c-lchzv:project-s2mch   Default
    Select a Project:

    After you enter a number, the console displays a message that you've changed projects.

    INFO[0005] Setting new context to project project-1
    INFO[0005] Saving config to /Users/markbishop/.ranchcli2.json

    Ensure you can run rancher kubectl get pods successfully.

    Commands​

    The following commands are available for use in Rancher CLI.

    CommandResult
    apps, [app]Performs operations on catalog applications (i.e., individual Helm charts) or Rancher charts.
    catalogPerforms operations on catalogs.
    clusters, [cluster]Performs operations on your clusters.
    contextSwitches between Rancher projects. For an example, see Project Selection.
    inspect [OPTIONS] [RESOURCEID RESOURCENAME]Displays details about Kubernetes resources or Rancher resources (i.e.: projects and workloads. Specify resources by name or ID.
    kubectlRuns kubectl commands.
    login, [l]Logs into a Rancher Server. For an example, see CLI Authentication.
    namespaces, [namespace]Performs operations on namespaces.
    nodes, [node]Performs operations on nodes.
    projects, [project]Performs operations on projects.
    psDisplays workloads in a project.
    settings, [setting]Shows the current settings for your Rancher Server.
    sshConnects to one of your cluster nodes using the SSH protocol.
    help, [h]Shows a list of commands or help for one command.

    Rancher CLI Help​

    Once logged into Rancher Server using the CLI, enter ./rancher --help for a list of commands.

    All commands accept the --help flag, which documents each command's usage.

    Limitations​

    The Rancher CLI cannot be used to install dashboard apps or Rancher feature charts.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html index b641c144401..ecc15c1e048 100644 --- a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html +++ b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/amazon-ec2.html @@ -5,13 +5,13 @@ EC2 Node Template Configuration | Rancher Manager - +
    Version: v2.5

    EC2 Node Template Configuration

    For more details about EC2, nodes, refer to the official documentation for the EC2 Management Console.

    Region​

    In the Region field, select the same region that you used when creating your cloud credentials.

    Cloud Credentials​

    Your AWS account access information, stored in a cloud credential.

    See Amazon Documentation: Creating Access Keys how to create an Access Key and Secret Key.

    See Amazon Documentation: Creating IAM Policies (Console) how to create an IAM policy.

    See Amazon Documentation: Adding Permissions to a User (Console) how to attach an IAM

    See our three example JSON policies:

    Authenticate & Configure Nodes​

    Choose an availability zone and network settings for your cluster.

    Security Group​

    Choose the default security group or configure a security group.

    Please refer to Amazon EC2 security group when using Node Driver to see what rules are created in the rancher-nodes Security Group.

    Instance Options​

    Configure the instances that will be created. Make sure you configure the correct SSH User for the configured AMI. It is possible that a selected region does not support the default instance type. In this scenario you must select an instance type that does exist, otherwise an error will occur stating the requested configuration is not supported.

    If you need to pass an IAM Instance Profile Name (not ARN), for example, when you want to use a Kubernetes Cloud Provider, you will need an additional permission in your policy. See Example IAM policy with PassRole for an example policy.

    Engine Options​

    In the Engine Options section of the node template, you can configure the Docker daemon. You may want to specify the docker version or a Docker registry mirror.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html index 6fdd41fa031..c0d78857752 100644 --- a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html +++ b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/azure.html @@ -5,13 +5,13 @@ Azure Node Template Configuration | Rancher Manager - +
    Version: v2.5

    Azure Node Template Configuration

    For more information about Azure, refer to the official Azure documentation.

    Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

    • Placement sets the geographical region where your cluster is hosted and other location metadata.
    • Network configures the networking used in your cluster.
    • Instance customizes your VM configuration.

    The Docker daemon configuration options include:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html index bafcde35950..d3c3595aef3 100644 --- a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html +++ b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/digitalocean.html @@ -5,13 +5,13 @@ DigitalOcean Node Template Configuration | Rancher Manager - +
    Version: v2.5

    DigitalOcean Node Template Configuration

    Account access information is stored as a cloud credential. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one.

    Droplet Options​

    The Droplet Options provision your cluster's geographical region and specifications.

    Docker Daemon​

    The Docker daemon configuration options include:

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html index 653ab053dff..919a0172e9d 100644 --- a/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html +++ b/v2.5/reference-guides/cluster-configuration/downstream-cluster-configuration/node-template-configuration/vsphere.html @@ -5,13 +5,13 @@ VSphere Node Template Configuration | Rancher Manager - +
    Version: v2.5

    VSphere Node Template Configuration

    The following node template configuration reference applies to Rancher v2.3.3+.

    Account Access​

    ParameterRequiredDescription
    Cloud Credentials*Your vSphere account access information, stored in a cloud credential.

    Your cloud credential has these fields:

    Credential FieldDescription
    vCenter or ESXi ServerEnter the vCenter or ESXi hostname/IP. ESXi is the virtualization platform where you create and run virtual machines and virtual appliances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.
    PortOptional: configure configure the port of the vCenter or ESXi server.
    Username and passwordEnter your vSphere login username and password.

    Scheduling

    Choose what hypervisor the virtual machine will be scheduled to.

    The fields in the Scheduling section should auto-populate with the data center and other scheduling options that are available to you in vSphere.

    FieldRequiredExplanation
    Data Center*Choose the name/path of the data center where the VM will be scheduled.
    Resource PoolName of the resource pool to schedule the VMs in. Resource pools can be used to partition available CPU and memory resources of a standalone host or cluster, and they can also be nested. Leave blank for standalone ESXi. If not specified, the default resource pool is used.
    Data Store*If you have a data store cluster, you can toggle the Data Store field. This lets you select a data store cluster where your VM will be scheduled to. If the field is not toggled, you can select an individual disk.
    FolderName of a folder in the datacenter to create the VMs in. Must already exist. The VM folders in this dropdown menu directly correspond to your VM folders in vSphere. The folder name should be prefaced with vm/ in your vSphere config file.
    HostThe IP of the host system to schedule VMs in. Leave this field blank for a standalone ESXi or for a cluster with DRS (Distributed Resource Scheduler). If specified, the host system's pool will be used and the Resource Pool parameter will be ignored.

    Instance Options​

    In the Instance Options section, configure the number of vCPUs, memory, and disk size for the VMs created by this template.

    ParameterRequiredDescription
    CPUs*Number of vCPUS to assign to VMs.
    Memory*Amount of memory to assign to VMs.
    Disk*Size of the disk (in MB) to attach to the VMs.
    Creation method*The method for setting up an operating system on the node. The operating system can be installed from an ISO or from a VM template. Depending on the creation method, you will also have to specify a VM template, content library, existing VM, or ISO. For more information on creation methods, refer to About VM Creation Methods.
    Cloud InitURL of a cloud-config.yml file or URL to provision VMs with. This file allows further customization of the operating system, such as network configuration, DNS servers, or system daemons. The operating system must support cloud-init.
    NetworksName(s) of the network to attach the VM to.
    Configuration Parameters used for guestinfoAdditional configuration parameters for the VMs. These correspond to the Advanced Settings in the vSphere console. Example use cases include providing RancherOS guestinfo parameters or enabling disk UUIDs for the VMs (disk.EnableUUID=TRUE).

    About VM Creation Methods​

    In the Creation method field, configure the method used to provision VMs in vSphere. Available options include creating VMs that boot from a RancherOS ISO or creating VMs by cloning from an existing virtual machine or VM template.

    The existing VM or template may use any modern Linux operating system that is configured with support for cloud-init using the NoCloud datasource.

    Choose the way that the VM will be created:

    • Deploy from template: Data Center: Choose a VM template that exists in the data center that you selected.
    • Deploy from template: Content Library: First, select the Content Library that contains your template, then select the template from the populated list Library templates.
    • Clone an existing virtual machine: In the Virtual machine field, choose an existing VM that the new VM will be cloned from.
    • Install from boot2docker ISO: Ensure that the OS ISO URL field contains the URL of a VMware ISO release for RancherOS (rancheros-vmware.iso). Note that this URL must be accessible from the nodes running your Rancher server installation.

    Networks​

    The node template now allows a VM to be provisioned with multiple networks. In the Networks field, you can now click Add Network to add any networks available to you in vSphere.

    Node Tags and Custom Attributes​

    Tags allow you to attach metadata to objects in the vSphere inventory to make it easier to sort and search for these objects.

    For tags, all your vSphere tags will show up as options to select from in your node template.

    In the custom attributes, Rancher will let you select all the custom attributes you have already set up in vSphere. The custom attributes are keys and you can enter values for each one.

    Note: Custom attributes are a legacy feature that will eventually be removed from vSphere.

    cloud-init​

    Cloud-init allows you to initialize your nodes by applying configuration on the first boot. This may involve things such as creating users, authorizing SSH keys or setting up the network.

    To make use of cloud-init initialization, create a cloud config file using valid YAML syntax and paste the file content in the the Cloud Init field. Refer to the cloud-init documentation. for a commented set of examples of supported cloud config directives.

    Note that cloud-init is not supported when using the ISO creation method.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html index 5c122b7502b..83c7487b481 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/eks-cluster-configuration.html @@ -5,7 +5,7 @@ EKS Cluster Configuration Reference | Rancher Manager - + @@ -13,7 +13,7 @@
    Version: v2.5

    EKS Cluster Configuration Reference

    Account Access​

    Complete each drop-down and field using the information obtained for your IAM policy.

    SettingDescription
    RegionFrom the drop-down choose the geographical region in which to build your cluster.
    Cloud CredentialsSelect the cloud credentials that you created for your IAM policy. For more information on creating cloud credentials in Rancher, refer to this page.

    Service Role​

    Choose a service role.

    Service RoleDescription
    Standard: Rancher generated service roleIf you choose this role, Rancher automatically adds a service role for use with the cluster.
    Custom: Choose from your existing service rolesIf you choose this role, Rancher lets you choose from service roles that you're already created within AWS. For more information on creating a custom service role in AWS, see the Amazon documentation.

    Secrets Encryption​

    Optional: To encrypt secrets, select or enter a key created in AWS Key Management Service (KMS)

    API Server Endpoint Access​

    Configuring Public/Private API access is an advanced use case. For details, refer to the EKS cluster endpoint access control documentation.

    Private-only API Endpoints​

    If you enable private and disable public API endpoint access when creating a cluster, then there is an extra step you must take in order for Rancher to connect to the cluster successfully. In this case, a pop-up will be displayed with a command that you will run on the cluster to register it with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster's Kubernetes API.

    There are two ways to avoid this extra manual step:

    • You can create the cluster with both private and public API endpoint access on cluster creation. You can disable public access after the cluster is created and in an active state and Rancher will continue to communicate with the EKS cluster.
    • You can ensure that Rancher shares a subnet with the EKS cluster. Then security groups can be used to enable Rancher to communicate with the cluster's API endpoint. In this case, the command to register the cluster is not needed, and Rancher will be able to communicate with your cluster. For more information on configuring security groups, refer to the security groups documentation.

    Public Access Endpoints​

    Optionally limit access to the public endpoint via explicit CIDR blocks.

    If you limit access to specific CIDR blocks, then it is recommended that you also enable the private access to avoid losing network communication to the cluster.

    One of the following is required to enable private access:

    • Rancher's IP must be part of an allowed CIDR block
    • Private access should be enabled, and Rancher must share a subnet with the cluster and have network access to the cluster, which can be configured with a security group

    For more information about public and private access to the cluster endpoint, refer to the Amazon EKS documentation.

    Subnet​

    OptionDescription
    Standard: Rancher generated VPC and SubnetWhile provisioning your cluster, Rancher generates a new VPC with 3 public subnets.
    Custom: Choose from your existing VPC and SubnetsWhile provisioning your cluster, Rancher configures your Control Plane and nodes to use a VPC and Subnet that you've already created in AWS.

    For more information, refer to the AWS documentation for Cluster VPC Considerations. Follow one of the sets of instructions below based on your selection from the previous step.

    Security Group​

    Amazon Documentation:

    Logging​

    Configure control plane logs to send to Amazon CloudWatch. You are charged the standard CloudWatch Logs data ingestion and storage costs for any logs sent to CloudWatch Logs from your clusters.

    Each log type corresponds to a component of the Kubernetes control plane. To learn more about these components, see Kubernetes Components in the Kubernetes documentation.

    For more information on EKS control plane logging, refer to the official documentation.

    Managed Node Groups​

    Amazon EKS managed node groups automate the provisioning and lifecycle management of nodes (Amazon EC2 instances) for Amazon EKS Kubernetes clusters.

    For more information about how node groups work and how they are configured, refer to the EKS documentation.

    Bring your own launch template​

    A launch template ID and version can be provided in order to easily configure the EC2 instances in a node group. If a launch template is provided, then none of the settings below will be configurable in Rancher. Therefore, using a launch template would require that all the necessary and desired settings from the list below would need to be specified in the launch template. Also note that if a launch template ID and version is provided, then only the template version can be updated. Using a new template ID would require creating a new managed node group.

    OptionDescriptionRequired/Optional
    Instance TypeChoose the hardware specs for the instance you're provisioning.Required
    Image IDSpecify a custom AMI for the nodes. Custom AMIs used with EKS must be configured properlyOptional
    Node Volume SizeThe launch template must specify an EBS volume with the desired sizeRequired
    SSH KeyA key to be added to the instances to provide SSH access to the nodesOptional
    User DataCloud init script in MIME multi-part formatOptional
    Instance Resource TagsTag each EC2 instance in the node groupOptional

    Rancher-managed launch templates​

    If you do not specify a launch template, then you will be able to configure the above options in the Rancher UI and all of them can be updated after creation. In order to take advantage of all of these options, Rancher will create and manage a launch template for you. Each cluster in Rancher will have one Rancher-managed launch template and each managed node group that does not have a specified launch template will have one version of the managed launch template. The name of this launch template will have the prefix "rancher-managed-lt-" followed by the display name of the cluster. In addition, the Rancher-managed launch template will be tagged with the key "rancher-managed-template" and value "do-not-modify-or-delete" to help identify it as Rancher-managed. It is important that this launch template and its versions not be modified, deleted, or used with any other clusters or managed node groups. Doing so could result in your node groups being "degraded" and needing to be destroyed and recreated.

    Custom AMIs​

    If you specify a custom AMI, whether in a launch template or in Rancher, then the image must be configured properly and you must provide user data to bootstrap the node. This is considered an advanced use case and understanding the requirements is imperative.

    If you specify a launch template that does not contain a custom AMI, then Amazon will use the EKS-optimized AMI for the Kubernetes version and selected region. You can also select a GPU enabled instance for workloads that would benefit from it.

    Note The GPU enabled instance setting in Rancher is ignored if a custom AMI is provided, either in the dropdown or in a launch template.

    Spot instances​

    Spot instances are now supported by EKS. If a launch template is specified, Amazon recommends that the template not provide an instance type. Instead, Amazon recommends providing multiple instance types. If the "Request Spot Instances" checkbox is enabled for a node group, then you will have the opportunity to provide multiple instance types.

    Note Any selection you made in the instance type dropdown will be ignored in this situation and you must specify at least one instance type to the "Spot Instance Types" section. Furthermore, a launch template used with EKS cannot request spot instances. Requesting spot instances must be part of the EKS configuration.

    Node Group Settings​

    The following settings are also configurable. All of these except for the "Node Group Name" are editable after the node group is created.

    OptionDescription
    Node Group NameThe name of the node group.
    Desired ASG SizeThe desired number of instances.
    Maximum ASG SizeThe maximum number of instances. This setting won't take effect until the Cluster Autoscaler is installed.
    Minimum ASG SizeThe minimum number of instances. This setting won't take effect until the Cluster Autoscaler is installed.
    LabelsKubernetes labels applied to the nodes in the managed node group. Note: Invalid labels can prevent upgrades or can prevent Rancher from starting. For details on label syntax requirements, see the Kubernetes documentation.
    TagsThese are tags for the managed node group and do not propagate to any of the associated resources.

    Configuring the Refresh Interval​

    The eks-refresh-cron setting is deprecated. It has been migrated to the eks-refresh setting, which is an integer representing seconds.

    The default value is 300 seconds.

    The syncing interval can be changed by running kubectl edit setting eks-refresh.

    If the eks-refresh-cron setting was previously set, the migration will happen automatically.

    The shorter the refresh window, the less likely any race conditions will occur, but it does increase the likelihood of encountering request limits that may be in place for AWS APIs.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html index 5bd7a805a57..fd6907f2c67 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/gke-cluster-configuration/gke-private-clusters.html @@ -5,7 +5,7 @@ Private Clusters | Rancher Manager - + @@ -15,7 +15,7 @@ Cloud NAT will

    If restricting both incoming and outgoing traffic to nodes is a requirement, follow the air-gapped installation instructions to set up a private container image registry on the VPC where the cluster is going to be, allowing the cluster nodes to access and download the images they need to run the cluster agent. If the control plane endpoint is also private, Rancher will need direct access to it.

    Private Control Plane Endpoint​

    If the cluster has a public endpoint exposed, Rancher will be able to reach the cluster, and no additional steps need to be taken. However, if the cluster has no public endpoint, then considerations must be made to ensure Rancher can access the cluster.

    Cloud NAT​

    Note Cloud NAT will incur charges.

    As above, if restricting outgoing internet access to the nodes is not a concern, then Google's Cloud NAT service can be used to allow the nodes to access the internet. While the cluster is provisioning, Rancher will provide a registration command to run on the cluster. Download the kubeconfig for the new cluster and run the provided kubectl command on the cluster. Gaining access to the cluster in order to run this command can be done by creating a temporary node or using an existing node in the VPC, or by logging on to or creating an SSH tunnel through one of the cluster nodes.

    Direct access​

    If the Rancher server is run on the same VPC as the cluster's control plane, it will have direct access to the control plane's private endpoint. The cluster nodes will need to have access to a private registry to download images as described above.

    You can also use services from Google such as Cloud VPN or Cloud Interconnect VLAN to facilitate connectivity between your organization's network and your Google VPC.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.html index c4b87a1ae63..dd26777332f 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rancherd-configuration-reference.html @@ -5,13 +5,13 @@ RancherD Configuration Reference | Rancher Manager - +
    Version: v2.5

    RancherD Configuration Reference

    Note: RancherD was an experimental feature available as part of Rancher v2.5.4 through v2.5.10 but is now deprecated and not available for recent releases.

    In RancherD, a server node is defined as a machine (bare-metal or virtual) running the rancherd server command. The server runs the Kubernetes API as well as Kubernetes workloads.

    An agent node is defined as a machine running the rancherd agent command. They don't run the Kubernetes API. To add nodes designated to run your apps and services, join agent nodes to your cluster.

    In the RancherD installation instructions, we recommend running three server nodes in the Rancher server cluster. Agent nodes are not required.

    Certificates for the Rancher Server

    Rancherd does not use cert-manager to provision certs. Instead RancherD allows you to bring your own self-signed or trusted certs by storing the .pem files in /etc/rancher/ssl/. When doing this you should also set the publicCA parameter to true in your HelmChartConfig. For more information on the HelmChartConfig, refer to the section about customizing the RancherD Helm chart.

    Private key: /etc/rancher/ssl/key.pem

    Certificate: /etc/rancher/ssl/cert.pem

    CA Certificate(self-signed): /etc/rancher/ssl/cacerts.pem

    Additional CA Certificate: /etc/ssl/certs/ca-additional.pem

    Node Taints

    By default, server nodes will be schedulable and thus your workloads can get launched on them. If you wish to have a dedicated control plane where no user workloads will run, you can use taints. The node-taint parameter will allow you to configure nodes with taints. Here is an example of adding a node taint to the config.yaml:

    node-taint:
      - "CriticalAddonsOnly=true:NoExecute"

    Customizing the RancherD Helm Chart

    Rancher is launched as a Helm chart using the cluster’s Helm integration. This means that you can easily customize the application through a manifest file describing your custom parameters.

    The RancherD chart provisions Rancher in a daemonset. It exposes hostport 8080/8443 down to the container port (80/443), and uses hostpath to mount certs if needed.

    RancherD uses helm-controller to bootstrap the RancherD chart. To provide a customized values.yaml file, the configuration options must be passed in through the helm-controller custom resource definition.

    Here is an example of the manifest:

    apiVersion: helm.cattle.io/v1
    kind: HelmChartConfig
    metadata:
      name: rancher
      namespace: kube-system
    spec:
      valuesContent: |
        publicCA: true

    Put this manifest on your host in /var/lib/rancher/rke2/server/manifests before running RancherD.

    Common Options​

    ParameterDefault ValueDescription
    addLocal"auto"string - Have Rancher detect and import the local Rancher server cluster
    auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
    auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
    auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
    auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
    auditLog.maxBackups1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
    auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
    debugfalsebool - set debug flag on rancher server
    extraEnv[]list - set additional environment variables for Rancher
    imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
    proxy" "*string - HTTP[S] proxy server for Rancher
    noProxy"127.0.0.0/8,10.0.0.0/8,cattle-system.svc,172.16.0.0/12,192.168.0.0/16"string - comma separated list of hostnames or ip address not to use the proxy
    resources{}map - rancher pod resource requests & limits
    rancherImage"rancher/rancher"string - rancher image source
    rancherImageTagsame as chart versionstring - rancher/rancher image tag
    rancherImagePullPolicy"IfNotPresent"string - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent"
    systemDefaultRegistry""string - private registry to be used for all system Docker images, e.g., [http://registry.example.com/]
    useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.
    publicCAfalsebool - Set to true if your cert is signed by a public CA

    RancherD Server CLI Options

    The command to run the Rancher management server is:

    rancherd server [OPTIONS]

    It can be run with the following options:

    Config​

    OptionDescription
    --config FILE, -c FILELoad configuration from FILE (default: "/etc/rancher/rke2/config.yaml")

    Logging​

    OptionDescription
    --debugTurn on debug logs

    Listener​

    OptionDescription
    --bind-address valueRancherD bind address (default: 0.0.0.0)
    --advertise-address valueIP address that apiserver uses to advertise to members of the cluster (default: node-external-ip/node-ip)
    --tls-san valueAdd additional hostname or IP as a Subject Alternative Name in the TLS cert

    Data​

    OptionDescription
    --data-dir value, -d valueFolder to hold state (default: "/var/lib/rancher/rancherd")

    Networking​

    OptionDescription
    --cluster-cidr valueNetwork CIDR to use for pod IPs (default: "10.42.0.0/16")
    --service-cidr valueNetwork CIDR to use for services IPs (default: "10.43.0.0/16")
    --cluster-dns valueCluster IP for coredns service. Should be in your service-cidr range (default: 10.43.0.10)
    --cluster-domain valueCluster Domain (default: "cluster.local")

    Cluster​

    OptionDescription
    --token value, -t valueShared secret used to join a server or agent to a cluster
    --token-file valueFile containing the cluster-secret/token

    Client​

    OptionDescription
    --write-kubeconfig value, -o valueWrite kubeconfig for admin client to this file
    --write-kubeconfig-mode valueWrite kubeconfig with this mode

    Flags​

    OptionDescription
    --kube-apiserver-arg valueCustomized flag for kube-apiserver process
    --kube-scheduler-arg valueCustomized flag for kube-scheduler process
    --kube-controller-manager-arg valueCustomized flag for kube-controller-manager process

    Database​

    OptionDescription
    --etcd-disable-snapshotsDisable automatic etcd snapshots
    --etcd-snapshot-schedule-cron valueSnapshot interval time in cron spec. eg. every 5 hours '* /5 * ' (default: "0 /12 * * *")
    --etcd-snapshot-retention valueNumber of snapshots to retain (default: 5)
    --etcd-snapshot-dir valueDirectory to save db snapshots. (Default location: ${data-dir}/db/snapshots)
    --cluster-reset-restore-path valuePath to snapshot file to be restored

    System Images Registry​

    OptionDescription
    --system-default-registry valuePrivate registry to be used for all system Docker images

    Components​

    OptionDescription
    --disable valueDo not deploy packaged components and delete any deployed components (valid items: rancherd-canal, rancherd-coredns, rancherd-ingress, rancherd-kube-proxy, rancherd-metrics-server)

    Cloud Provider​

    OptionDescription
    --cloud-provider-name valueCloud provider name
    --cloud-provider-config valueCloud provider configuration file path

    Security​

    OptionDescription
    --profile valueValidate system configuration against the selected benchmark (valid items: cis-1.5)

    Agent Node​

    OptionDescription
    --node-name valueNode name
    --node-label valueRegistering and starting kubelet with set of labels
    --node-taint valueRegistering kubelet with set of taints
    --protect-kernel-defaultsKernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.
    --selinuxEnable SELinux in containerd

    Agent Runtime​

    OptionDescription
    --container-runtime-endpoint valueDisable embedded containerd and use alternative CRI implementation
    --snapshotter valueOverride default containerd snapshotter (default: "overlayfs")
    --private-registry valuePrivate registry configuration file (default: "/etc/rancher/rke2/registries.yaml")

    Agent Networking​

    OptionDescription
    --node-ip value, -i valueIP address to advertise for node
    --resolv-conf valueKubelet resolv.conf file

    Agent Flags​

    OptionDescription
    --kubelet-arg valueCustomized flag for kubelet process
    --kube-proxy-arg valueCustomized flag for kube-proxy process

    Experimental​

    OptionDescription
    --agent-token valueShared secret used to join agents to the cluster, but not servers
    --agent-token-file valueFile containing the agent secret
    --server value, -s valueServer to connect to, used to join a cluster
    --cluster-resetForget all peers and become sole member of a new cluster
    --secrets-encryptionEnable Secret encryption at rest

    RancherD Agent CLI Options

    The following command is used to run the RancherD agent:

    rancherd agent [OPTIONS]

    The following options are available.

    Config​

    OptionDescription
    --config FILE, -c FILELoad configuration from FILE (default: "/etc/rancher/rke2/config.yaml")

    Data​

    OptionDescription
    --data-dir value, -d valueFolder to hold state (default: "/var/lib/rancher/rancherd")

    Logging​

    OptionDescription
    --debugTurn on debug logs

    Cluster​

    OptionDescription
    --token value, -t valueToken to use for authentication
    --token-file valueToken file to use for authentication
    --server value, -s valueServer to connect to

    Agent Node​

    OptionDescription
    --node-name valueNode name
    --node-label valueRegistering and starting kubelet with set of labels
    --node-taint valueRegistering kubelet with set of taints
    --selinuxEnable SELinux in containerd
    --protect-kernel-defaultsKernel tuning behavior. If set, error if kernel tunables are different than kubelet defaults.

    Agent Runtime​

    OptionDescription
    --container-runtime-endpoint valueDisable embedded containerd and use alternative CRI implementation
    --snapshotter valueOverride default containerd snapshotter (default: "overlayfs")
    --private-registry valuePrivate registry configuration file (default: "/etc/rancher/rke2/registries.yaml")

    Agent Networking​

    OptionDescription
    --node-ip value, -i valueIP address to advertise for node
    --resolv-conf valueKubelet resolv.conf file

    Agent Flags​

    OptionDescription
    --kubelet-arg valueCustomized flag for kubelet process
    --kube-proxy-arg valueCustomized flag for kube-proxy process

    System Images Registry​

    OptionDescription
    --system-default-registry valuePrivate registry to be used for all system Docker images

    Cloud Provider​

    OptionDescription
    --cloud-provider-name valueCloud provider name
    --cloud-provider-config valueCloud provider configuration file path

    Security​

    OptionDescription
    --profile valueValidate system configuration against the selected benchmark (valid items: cis-1.5)
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html index d267555b082..4c836d2ae2d 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/rke1-cluster-configuration.html @@ -5,13 +5,13 @@ RKE Cluster Configuration | Rancher Manager - +
    Version: v2.5

    RKE Cluster Configuration

    In clusters launched by RKE, you can edit any of the remaining options that follow.

    Configuration Options in the Rancher UI

    To edit your cluster, open the Global view, make sure the Clusters tab is selected, and then select ⋮ > Edit for the cluster that you want to edit.

    Some advanced configuration options are not exposed in the Rancher UI forms, but they can be enabled by editing the RKE cluster configuration file in YAML. For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    Kubernetes Version​

    The version of Kubernetes installed on each cluster node. For more detail, see Upgrading Kubernetes.

    Network Provider​

    The \container networking interface (CNI) that powers networking for your cluster.

    Note: You can only choose this option while provisioning your cluster. It cannot be edited later.

    Project Network Isolation​

    If your network provider allows project network isolation, you can choose whether to enable or disable inter-project communication.

    Before Rancher v2.5.8, project network isolation is only available if you are using the Canal network plugin for RKE.

    In v2.5.8+, project network isolation is available if you are using any RKE network plugin that supports the enforcement of Kubernetes network policies, such as Canal or the Cisco ACI plugin.

    Nginx Ingress​

    If you want to publish your applications in a high-availability configuration, and you're hosting your nodes with a cloud-provider that doesn't have a native load-balancing feature, enable this option to use Nginx ingress within the cluster.

    Metrics Server Monitoring​

    Each cloud provider capable of launching a cluster using RKE can collect metrics and monitor for your cluster nodes. Enable this option to view your node metrics from your cloud provider's portal.

    Pod Security Policy Support​

    Enables pod security policies for the cluster. After enabling this option, choose a policy using the Default Pod Security Policy drop-down.

    Docker version on nodes​

    Configures whether nodes are allowed to run versions of Docker that Rancher doesn't officially support. If you choose to require a supported Docker version, Rancher will stop pods from running on nodes that don't have a supported Docker version installed.

    Docker Root Directory​

    The directory on your cluster nodes where you've installed Docker. If you install Docker on your nodes to a non-default directory, update this path.

    Default Pod Security Policy​

    If you enable Pod Security Policy Support, use this drop-down to choose the pod security policy that's applied to the cluster.

    Cloud Provider​

    If you're using a cloud provider to host cluster nodes launched by RKE, enable this option so that you can use the cloud provider's native features. If you want to store persistent data for your cloud-hosted cluster, this option is required.

    Editing Clusters with YAML

    Instead of using the Rancher UI to choose Kubernetes options for the cluster, advanced users can create an RKE config file. Using a config file allows you to set any of the options available in an RKE installation, except for system_images configuration, by specifying them in YAML.

    • To edit an RKE config file directly from the Rancher UI, click Edit as YAML.
    • To read from an existing RKE file, click Read from File.

    image

    For an example of RKE config file syntax, see the RKE documentation.

    For the complete reference of configurable options for RKE Kubernetes clusters in YAML, see the RKE documentation.

    Updating ingress-nginx

    Clusters that were created before Kubernetes 1.16 will have an ingress-nginx updateStrategy of OnDelete. Clusters that were created with Kubernetes 1.16 or newer will have RollingUpdate.

    If the updateStrategy of ingress-nginx is OnDelete, you will need to delete these pods to get the correct version for your deployment.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html index 6cd2fdee869..98acd898ad8 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/sync-clusters.html @@ -5,13 +5,13 @@ Syncing | Rancher Manager - +
    Version: v2.5

    Syncing

    Syncing is the feature for EKS and GKE clusters that causes Rancher to update the clusters' values so they are up to date with their corresponding cluster object in the hosted Kubernetes provider. This enables Rancher to not be the sole owner of a hosted cluster’s state. Its largest limitation is that processing an update from Rancher and another source at the same time or within 5 minutes of one finishing may cause the state from one source to completely overwrite the other.

    How it works​

    There are two fields on the Rancher Cluster object that must be understood to understand how syncing works:

    1. The config object for the cluster, located on the Spec of the Cluster:

      • For EKS, the field is called EKSConfig
      • For GKE, the field is called GKEConfig

    2. The UpstreamSpec object

      • For EKS, this is located on the EKSStatus field on the Status of the Cluster.
      • For GKE, this is located on the GKEStatus field on the Status of the Cluster.

    The struct types that define these objects can be found in their corresponding operator projects:

    All fields with the exception of the cluster name, the location (region or zone), Imported, and the cloud credential reference, are nillable on this Spec object.

    The EKSConfig or GKEConfig represents desired state for its non-nil values. Fields that are non-nil in the config object can be thought of as “managed". When a cluster is created in Rancher, all fields are non-nil and therefore “managed”. When a pre-existing cluster is registered in rancher all nillable fields are nil and are not “managed”. Those fields become managed once their value has been changed by Rancher.

    UpstreamSpec represents the cluster as it is in the hosted Kubernetes provider and is refreshed on an interval of 5 minutes. After the UpstreamSpec has been refreshed, Rancher checks if the cluster has an update in progress. If it is updating, nothing further is done. If it is not currently updating, any “managed” fields on EKSConfig or GKEConfig are overwritten with their corresponding value from the recently updated UpstreamSpec.

    The effective desired state can be thought of as the UpstreamSpec + all non-nil fields in the EKSConfig or GKEConfig. This is what is displayed in the UI.

    If Rancher and another source attempt to update a cluster at the same time or within the 5 minute refresh window of an update finishing, then it is likely any “managed” fields can be caught in a race condition. To use EKS as an example, a cluster may have PrivateAccess as a managed field. If PrivateAccess is false and then enabled in EKS console, then finishes at 11:01, and then tags are updated from Rancher before 11:05 the value will likely be overwritten. This would also occur if tags were updated while the cluster was processing the update. If the cluster was registered and the PrivateAccess fields was nil then this issue should not occur in the aforementioned case.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html index 5f64386a8c7..9ab9ba63ab1 100644 --- a/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html +++ b/v2.5/reference-guides/cluster-configuration/rancher-server-configuration/use-existing-nodes/rancher-agent-options.html @@ -5,13 +5,13 @@ Rancher Agent Options | Rancher Manager - +
    Version: v2.5

    Rancher Agent Options

    Rancher deploys an agent on each node to communicate with the node. This pages describes the options that can be passed to the agent. To use these options, you will need to create a cluster with custom nodes and add the options to the generated docker run command when adding a node.

    For an overview of how Rancher communicates with downstream clusters using node agents, refer to the architecture section.

    General options​

    ParameterEnvironment variableDescription
    --serverCATTLE_SERVERThe configured Rancher server-url setting which the agent connects to
    --tokenCATTLE_TOKENToken that is needed to register the node in Rancher
    --ca-checksumCATTLE_CA_CHECKSUMThe SHA256 checksum of the configured Rancher cacerts setting to validate
    --node-nameCATTLE_NODE_NAMEOverride the hostname that is used to register the node (defaults to hostname -s)
    --labelCATTLE_NODE_LABELAdd node labels to the node. For multiple labels, pass additional --label options. (--label key=value)
    --taintsCATTLE_NODE_TAINTSAdd node taints to the node. For multiple taints, pass additional --taints options. (--taints key=value:effect)

    Role options​

    ParameterEnvironment variableDescription
    --all-rolesALL=trueApply all roles (etcd,controlplane,worker) to the node
    --etcdETCD=trueApply the role etcd to the node
    --controlplaneCONTROL=trueApply the role controlplane to the node
    --workerWORKER=trueApply the role worker to the node

    IP address options​

    ParameterEnvironment variableDescription
    --addressCATTLE_ADDRESSThe IP address the node will be registered with (defaults to the IP used to reach 8.8.8.8)
    --internal-addressCATTLE_INTERNAL_ADDRESSThe IP address used for inter-host communication on a private network

    Dynamic IP address options​

    For automation purposes, you can't have a specific IP address in a command as it has to be generic to be used for every node. For this, we have dynamic IP address options. They are used as a value to the existing IP address options. This is supported for --address and --internal-address.

    ValueExampleDescription
    Interface name--address eth0The first configured IP address will be retrieved from the given interface
    ipify--address ipifyValue retrieved from https://api.ipify.org will be used
    awslocal--address awslocalValue retrieved from http://169.254.169.254/latest/meta-data/local-ipv4 will be used
    awspublic--address awspublicValue retrieved from http://169.254.169.254/latest/meta-data/public-ipv4 will be used
    doprivate--address doprivateValue retrieved from http://169.254.169.254/metadata/v1/interfaces/private/0/ipv4/address will be used
    dopublic--address dopublicValue retrieved from http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address will be used
    azprivate--address azprivateValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/privateIpAddress?api-version=2017-08-01&format=text will be used
    azpublic--address azpublicValue retrieved from http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text will be used
    gceinternal--address gceinternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/ip will be used
    gceexternal--address gceexternalValue retrieved from http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip will be used
    packetlocal--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/local-ipv4 will be used
    packetpublic--address packetlocalValue retrieved from https://metadata.packet.net/2009-04-04/meta-data/public-ipv4 will be used
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/configure-openldap/openldap-config-reference.html b/v2.5/reference-guides/configure-openldap/openldap-config-reference.html index fed2b51e3b3..42681369c72 100644 --- a/v2.5/reference-guides/configure-openldap/openldap-config-reference.html +++ b/v2.5/reference-guides/configure-openldap/openldap-config-reference.html @@ -5,13 +5,13 @@ OpenLDAP Configuration Reference | Rancher Manager - +
    Version: v2.5

    OpenLDAP Configuration Reference

    This section is intended to be used as a reference when setting up an OpenLDAP authentication provider in Rancher.

    For further details on configuring OpenLDAP, refer to the official documentation.

    Before you proceed with the configuration, please familiarize yourself with the concepts of External Authentication Configuration and Principal Users.

    Background: OpenLDAP Authentication Flow​

    1. When a user attempts to login with his LDAP credentials, Rancher creates an initial bind to the LDAP server using a service account with permissions to search the directory and read user/group attributes.
    2. Rancher then searches the directory for the user by using a search filter based on the provided username and configured attribute mappings.
    3. Once the user has been found, he is authenticated with another LDAP bind request using the user's DN and provided password.
    4. Once authentication succeeded, Rancher then resolves the group memberships both from the membership attribute in the user's object and by performing a group search based on the configured user mapping attribute.

    OpenLDAP Server Configuration

    You will need to enter the address, port, and protocol to connect to your OpenLDAP server. 389 is the standard port for insecure traffic, 636 for TLS traffic.

    Using TLS?

    If the certificate used by the OpenLDAP server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.

    If you are in doubt about the correct values to enter in the user/group Search Base configuration fields, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

    OpenLDAP Server Parameters
    ParameterDescription
    HostnameSpecify the hostname or IP address of the OpenLDAP server
    PortSpecify the port at which the OpenLDAP server is listening for connections. Unencrypted LDAP normally uses the standard port of 389, while LDAPS uses port 636.
    TLSCheck this box to enable LDAP over SSL/TLS (commonly known as LDAPS). You will also need to paste in the CA certificate if the server uses a self-signed/enterprise-signed certificate.
    Server Connection TimeoutThe duration in number of seconds that Rancher waits before considering the server unreachable.
    Service Account Distinguished NameEnter the Distinguished Name (DN) of the user that should be used to bind, search and retrieve LDAP entries.
    Service Account PasswordThe password for the service account.
    User Search BaseEnter the Distinguished Name of the node in your directory tree from which to start searching for user objects. All users must be descendents of this base DN. For example: "ou=people,dc=acme,dc=com".
    Group Search BaseIf your groups live under a different node than the one configured under User Search Base you will need to provide the Distinguished Name here. Otherwise leave this field empty. For example: "ou=groups,dc=acme,dc=com".

    User/Group Schema Configuration

    If your OpenLDAP directory deviates from the standard OpenLDAP schema, you must complete the Customize Schema section to match it.

    Note that the attribute mappings configured in this section are used by Rancher to construct search filters and resolve group membership. It is therefore always recommended to verify that the configuration here matches the schema used in your OpenLDAP.

    If you are unfamiliar with the user/group schema used in the OpenLDAP server, consult your LDAP administrator or refer to the section Identify Search Base and Schema using ldapsearch in the Active Directory authentication documentation.

    User Schema Configuration​

    The table below details the parameters for the user schema configuration.

    User Schema Configuration Parameters
    ParameterDescription
    Object ClassThe name of the object class used for user objects in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Username AttributeThe user attribute whose value is suitable as a display name.
    Login AttributeThe attribute whose value matches the username part of credentials entered by your users when logging in to Rancher. This is typically uid.
    User Member AttributeThe user attribute containing the Distinguished Name of groups a user is member of. Usually this is one of memberOf or isMemberOf.
    Search AttributeWhen a user enters text to add users or groups in the UI, Rancher queries the LDAP server and attempts to match users by the attributes provided in this setting. Multiple attributes can be specified by separating them with the pipe ("|") symbol.
    User Enabled AttributeIf the schema of your OpenLDAP server supports a user attribute whose value can be evaluated to determine if the account is disabled or locked, enter the name of that attribute. The default OpenLDAP schema does not support this and the field should usually be left empty.
    Disabled Status BitmaskThis is the value for a disabled/locked user account. The parameter is ignored if User Enabled Attribute is empty.

    Group Schema Configuration​

    The table below details the parameters for the group schema configuration.

    Group Schema Configuration Parameters
    ParameterDescription
    Object ClassThe name of the object class used for group entries in your domain. If defined, only specify the name of the object class - don't include it in an LDAP wrapper such as &(objectClass=xxxx)
    Name AttributeThe group attribute whose value is suitable for a display name.
    Group Member User AttributeThe name of the user attribute whose format matches the group members in the Group Member Mapping Attribute.
    Group Member Mapping AttributeThe name of the group attribute containing the members of a group.
    Search AttributeAttribute used to construct search filters when adding groups to clusters or projects in the UI. See description of user schema Search Attribute.
    Group DN AttributeThe name of the group attribute whose format matches the values in the user's group membership attribute. See User Member Attribute.
    Nested Group MembershipThis settings defines whether Rancher should resolve nested group memberships. Use only if your organization makes use of these nested memberships (ie. you have groups that contain other groups as members). This option is disabled if you are using Shibboleth.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/installation-references/feature-flags.html b/v2.5/reference-guides/installation-references/feature-flags.html index ef4077ee307..6794444d6db 100644 --- a/v2.5/reference-guides/installation-references/feature-flags.html +++ b/v2.5/reference-guides/installation-references/feature-flags.html @@ -5,13 +5,13 @@ Feature Flags | Rancher Manager - +
    Version: v2.5

    Feature Flags

    Feature flags were introduced to allow you to try experimental features that are not enabled by default.

    To learn about feature values and how to enable features, refer here.

    note

    There are some feature flags that may require a restart of the Rancher server container. These features that require a restart are marked in the table of these docs and in the UI.

    The following is a list of the feature flags available in Rancher:

    The below table shows the availability and default value for feature flags in Rancher:

    Feature Flag NameDefault ValueStatusAvailable as ofRancher Restart Required?
    dashboardtrueExperimentalv2.4.0X
    dashboardtrueGA* and no longer a feature flagv2.5.0X
    istio-virtual-service-uifalseExperimentalv2.3.0
    istio-virtual-service-uitrueGA*v2.3.2
    proxyfalseExperimentalv2.4.0
    proxyN/ADiscontinuedv2.5.0X
    unsupported-storage-driversfalseExperimentalv2.3.0
    fleettrueGA*v2.5.0

    * Generally Available. This feature is included in Rancher and it is not experimental.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/installation-references/helm-chart-options.html b/v2.5/reference-guides/installation-references/helm-chart-options.html index 9cb3125c802..0d1520f7e73 100644 --- a/v2.5/reference-guides/installation-references/helm-chart-options.html +++ b/v2.5/reference-guides/installation-references/helm-chart-options.html @@ -5,13 +5,13 @@ Rancher Helm Chart Options | Rancher Manager - +
    Version: v2.5

    Rancher Helm Chart Options

    This page is a configuration reference for the Rancher Helm chart.

    For help choosing a Helm chart version, refer to this page.

    For information on enabling experimental features, refer to this page.

    Common Options​

    OptionDefault ValueDescription
    hostname" "string - the Fully Qualified Domain Name for your Rancher Server
    ingress.tls.source"rancher"string - Where to get the cert for the ingress. - "rancher, letsEncrypt, secret"
    letsEncrypt.email" "string - Your email address
    letsEncrypt.environment"production"string - Valid options: "staging, production"
    privateCAfalsebool - Set to true if your cert is signed by a private CA

    Advanced Options​

    OptionDefault ValueDescription
    additionalTrustedCAsfalsebool - See Additional Trusted CAs
    addLocal"true"string - Have Rancher detect and import the "local" Rancher server cluster. Note: This option is no longer available in v2.5.0. Consider using the restrictedAdmin option to prevent users from modifying the local cluster.
    antiAffinity"preferred"string - AntiAffinity rule for Rancher pods - "preferred, required"
    auditLog.destination"sidecar"string - Stream to sidecar container console or hostPath volume - "sidecar, hostPath"
    auditLog.hostPath"/var/log/rancher/audit"string - log file destination on host (only applies when auditLog.destination is set to hostPath)
    auditLog.level0int - set the API Audit Log level. 0 is off. [0-3]
    auditLog.maxAge1int - maximum number of days to retain old audit log files (only applies when auditLog.destination is set to hostPath)
    auditLog.maxBackup1int - maximum number of audit log files to retain (only applies when auditLog.destination is set to hostPath)
    auditLog.maxSize100int - maximum size in megabytes of the audit log file before it gets rotated (only applies when auditLog.destination is set to hostPath)
    busyboxImage"busybox"string - Image location for busybox image used to collect audit logs
    certmanager.version""string - set cert-manager compatibility
    debugfalsebool - set debug flag on rancher server
    extraEnv[]list - set additional environment variables for Rancher
    imagePullSecrets[]list - list of names of Secret resource containing private registry credentials
    ingress.configurationSnippet""string - Add additional Nginx configuration. Can be used for proxy configuration.
    ingress.extraAnnotations{}map - additional annotations to customize the ingress
    ingress.enabledtrueWhen set to false, Helm will not install a Rancher ingress. Set the option to false to deploy your own ingress. Available as of v2.5.6
    letsEncrypt.ingress.class""string - optional ingress class for the cert-manager acmesolver ingress that responds to the Let's Encrypt ACME challenges. Options: traefik, nginx.
    noProxy"127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local,cattle-system.svc"string - comma separated list of hostnames or ip address not to use the proxy
    proxy""string - HTTP[S] proxy server for Rancher
    rancherImage"rancher/rancher"string - rancher image source
    rancherImagePullPolicy"IfNotPresent"string - Override imagePullPolicy for rancher server images - "Always", "Never", "IfNotPresent"
    rancherImageTagsame as chart versionstring - rancher/rancher image tag
    replicas3int - Number of replicas of Rancher pods
    resources{}map - rancher pod resource requests & limits
    restrictedAdminfalseAvailable in Rancher v2.5 bool - When this option is set to true, the initial Rancher user has restricted access to the local Kubernetes cluster to prevent privilege escalation. For more information, see the section about the restricted-admin role.
    systemDefaultRegistry""string - private registry to be used for all system Docker images, e.g., registry.example.com
    tls"ingress"string - See External TLS Termination for details. - "ingress, external"
    useBundledSystemChartfalsebool - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations.

    API Audit Log​

    Enabling the API Audit Log.

    You can collect this log as you would any container log. Enable logging for the System Project on the Rancher server cluster.

    --set auditLog.level=1

    By default enabling Audit Logging will create a sidecar container in the Rancher pod. This container (rancher-audit-log) will stream the log to stdout. You can collect this log as you would any container log. When using the sidecar as the audit log destination, the hostPath, maxAge, maxBackups, and maxSize options do not apply. It's advised to use your OS or Docker daemon's log rotation features to control disk space use. Enable logging for the Rancher server cluster or System Project.

    Set the auditLog.destination to hostPath to forward logs to volume shared with the host system instead of streaming to a sidecar container. When setting the destination to hostPath you may want to adjust the other auditLog parameters for log rotation.

    Setting Extra Environment Variables​

    You can set extra environment variables for Rancher server using extraEnv. This list uses the same name and value keys as the container manifest definitions. Remember to quote the values.

    --set 'extraEnv[0].name=CATTLE_TLS_MIN_VERSION'
    --set 'extraEnv[0].value=1.0'

    TLS Settings​

    When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller.

    See TLS settings for more information and options.

    Import local Cluster​

    By default Rancher server will detect and import the local cluster it's running on. User with access to the local cluster will essentially have "root" access to all the clusters managed by Rancher server.

    Important: If you turn addLocal off, most Rancher v2.5 features won't work, including the EKS provisioner.

    If this is a concern in your environment you can set this option to "false" on your initial install.

    This option is only effective on the initial Rancher install. See Issue 16522 for more information.

    --set addLocal="false"

    Customizing your Ingress​

    To customize or use a different ingress with Rancher server you can set your own Ingress annotations.

    Example on setting a custom certificate issuer:

    --set ingress.extraAnnotations.'cert-manager\.io/cluster-issuer'=issuer-name

    Example on setting a static proxy header with ingress.configurationSnippet. This value is parsed like a template so variables can be used.

    --set ingress.configurationSnippet='more_set_input_headers X-Forwarded-Host {{ .Values.hostname }};'

    HTTP Proxy​

    Rancher requires internet access for some functionality (helm charts). Use proxy to set your proxy server.

    Add your IP exceptions to the noProxy list. Make sure you add the Pod cluster IP range (default: 10.42.0.0/16), Service cluster IP range (default: 10.43.0.0/16), the internal cluster domains (default: .svc,.cluster.local) and any worker cluster controlplane nodes. Rancher supports CIDR notation ranges in this list.

    --set proxy="http://<username>:<password>@<proxy_url>:<proxy_port>/"
    --set noProxy="127.0.0.0/8\,10.0.0.0/8\,172.16.0.0/12\,192.168.0.0/16\,.svc\,.cluster.local"

    Additional Trusted CAs​

    If you have private registries, catalogs or a proxy that intercepts certificates, you may need to add additional trusted CAs to Rancher.

    --set additionalTrustedCAs=true

    Once the Rancher deployment is created, copy your CA certs in pem format into a file named ca-additional.pem and use kubectl to create the tls-ca-additional secret in the cattle-system namespace.

    kubectl -n cattle-system create secret generic tls-ca-additional --from-file=ca-additional.pem=./ca-additional.pem

    Private Registry and Air Gap Installs​

    For details on installing Rancher with a private registry, see Air Gapped Helm CLI Install.

    External TLS Termination

    We recommend configuring your load balancer as a Layer 4 balancer, forwarding plain 80/tcp and 443/tcp to the Rancher Management cluster nodes. The Ingress Controller on the cluster will redirect http traffic on port 80 to https on port 443.

    You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the --set tls=external option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer.

    Note: If you are using a Private CA signed certificate, add --set privateCA=true and see Adding TLS Secrets - Using a Private CA Signed Certificate to add the CA cert for Rancher.

    Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.

    Configuring Ingress for External TLS when Using NGINX v0.25​

    In NGINX v0.25, the behavior of NGINX has changed regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.25, you must edit the cluster.yml to enable the use-forwarded-headers option for ingress:

    ingress:
      provider: nginx
      options:
        use-forwarded-headers: 'true'

    Required Headers​

    • Host
    • X-Forwarded-Proto
    • X-Forwarded-Port
    • X-Forwarded-For
    • Read Timeout: 1800 seconds
    • Write Timeout: 1800 seconds
    • Connect Timeout: 30 seconds

    Health Checks​

    Rancher will respond 200 to health checks on the /healthz endpoint.

    Example NGINX config​

    This NGINX configuration is tested on NGINX 1.14.

    Note: This NGINX configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - HTTP Load Balancing.

    • Replace IP_NODE1, IP_NODE2 and IP_NODE3 with the IP addresses of the nodes in your cluster.
    • Replace both occurrences of FQDN to the DNS name for Rancher.
    • Replace /certs/fullchain.pem and /certs/privkey.pem to the location of the server certificate and the server certificate key respectively.
    worker_processes 4;
    worker_rlimit_nofile 40000;

    events {
        worker_connections 8192;
    }

    http {
        upstream rancher {
            server IP_NODE_1:80;
            server IP_NODE_2:80;
            server IP_NODE_3:80;
        }

        map $http_upgrade $connection_upgrade {
            default Upgrade;
            ''      close;
        }

        server {
            listen 443 ssl http2;
            server_name FQDN;
            ssl_certificate /certs/fullchain.pem;
            ssl_certificate_key /certs/privkey.pem;

            location / {
                proxy_set_header Host $host;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_pass http://rancher;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
                proxy_read_timeout 900s;
                proxy_buffering off;
            }
        }

        server {
            listen 80;
            server_name FQDN;
            return 301 https://$server_name$request_uri;
        }
    }
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/installation-references/tls-settings.html b/v2.5/reference-guides/installation-references/tls-settings.html index 700c9d5bc03..af3c5a3a57c 100644 --- a/v2.5/reference-guides/installation-references/tls-settings.html +++ b/v2.5/reference-guides/installation-references/tls-settings.html @@ -5,13 +5,13 @@ TLS Settings | Rancher Manager - +
    Version: v2.5

    TLS Settings

    Changing the default TLS settings depends on the chosen installation method.

    Running Rancher in a highly available Kubernetes cluster

    When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller:

    Running Rancher in a single Docker container

    The default TLS configuration only accepts TLS 1.2 and secure TLS cipher suites. You can change this by setting the following environment variables:

    ParameterDescriptionDefaultAvailable options
    CATTLE_TLS_MIN_VERSIONMinimum TLS version1.21.0, 1.1, 1.2, 1.3
    CATTLE_TLS_CIPHERSAllowed TLS cipher suitesTLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    		See Golang tls constants
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/kubernetes-concepts.html b/v2.5/reference-guides/kubernetes-concepts.html index 2c33206c640..9d3859fb7a2 100644 --- a/v2.5/reference-guides/kubernetes-concepts.html +++ b/v2.5/reference-guides/kubernetes-concepts.html @@ -5,13 +5,13 @@ Kubernetes Concepts | Rancher Manager - +
    Version: v2.5

    Kubernetes Concepts

    This page explains concepts related to Kubernetes that are important for understanding how Rancher works. The descriptions below provide a simplified interview of Kubernetes components. For more details, refer to the official documentation on Kubernetes components.

    About Docker​

    Docker is the container packaging and runtime standard. Developers build container images from Dockerfiles and distribute container images from Docker registries. Docker Hub is the most popular public registry. Many organizations also set up private Docker registries. Docker is primarily used to manage containers on individual nodes.

    Note: Although Rancher 1.6 supported Docker Swarm clustering technology, it is no longer supported in Rancher 2.x due to the success of Kubernetes.

    About Kubernetes​

    Kubernetes is the container cluster management standard. YAML files specify containers and other resources that form an application. Kubernetes performs functions such as scheduling, scaling, service discovery, health check, secret management, and configuration management.

    What is a Kubernetes Cluster?​

    A cluster is a group of computers that work together as a single system.

    A Kubernetes Cluster is a cluster that uses the Kubernetes container-orchestration system to deploy, maintain, and scale Docker containers, allowing your organization to automate application operations.

    Roles for Nodes in Kubernetes Clusters​

    Each computing resource in a Kubernetes cluster is called a node. Nodes can be either bare-metal servers or virtual machines. Kubernetes classifies nodes into three types: etcd nodes, control plane nodes, and worker nodes.

    A Kubernetes cluster consists of at least one etcd, controlplane, and worker node.

    etcd Nodes​

    Rancher uses etcd as a data store in both single node and high-availability installations. In Kubernetes, etcd is also a role for nodes that store the cluster state.

    The state of a Kubernetes cluster is maintained in etcd. The etcd nodes run the etcd database.

    The etcd database component is a distributed key-value store used as Kubernetes storage for all cluster data, such as cluster coordination and state management. It is recommended to run etcd on multiple nodes so that there's always a backup available for failover.

    Although you can run etcd on just one node, etcd requires a majority of nodes, a quorum, to agree on updates to the cluster state. The cluster should always contain enough healthy etcd nodes to form a quorum. For a cluster with n members, a quorum is (n/2)+1. For any odd-sized cluster, adding one node will always increase the number of nodes necessary for a quorum.

    Three etcd nodes is generally sufficient for smaller clusters and five etcd nodes for large clusters.

    Controlplane Nodes​

    Controlplane nodes run the Kubernetes API server, scheduler, and controller manager. These nodes take care of routine tasks to ensure that your cluster maintains your configuration. Because all cluster data is stored on your etcd nodes, control plane nodes are stateless. You can run control plane on a single node, although three or more nodes are recommended for redundancy. Additionally, a single node can share the control plane and etcd roles.

    Worker Nodes​

    Each worker node runs the following:

    • Kubelets: An agent that monitors the state of the node, ensuring your containers are healthy.
    • Workloads: The containers and pods that hold your apps, as well as other types of deployments.

    Worker nodes also run storage and networking drivers, and ingress controllers when required. You create as many worker nodes as necessary to run your workloads.

    About Helm​

    For high-availability installations of Rancher, Helm is the tool used to install Rancher on a Kubernetes cluster.

    Helm is the package management tool of choice for Kubernetes. Helm charts provide templating syntax for Kubernetes YAML manifest documents. With Helm we can create configurable deployments instead of just using static files. For more information about creating your own catalog of deployments, check out the docs at https://helm.sh/.

    For more information on service accounts and cluster role binding, refer to the Kubernetes documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/monitoring-v2-configuration/examples.html b/v2.5/reference-guides/monitoring-v2-configuration/examples.html index afc183588cf..5fb6f1e8c03 100644 --- a/v2.5/reference-guides/monitoring-v2-configuration/examples.html +++ b/v2.5/reference-guides/monitoring-v2-configuration/examples.html @@ -5,13 +5,13 @@ Examples | Rancher Manager - +
    Version: v2.5

    Examples

    ServiceMonitor​

    An example ServiceMonitor custom resource can be found here.

    PodMonitor​

    An example PodMonitor can be found here. An example Prometheus resource that refers to it can be found here.

    PrometheusRule​

    For users who are familiar with Prometheus, a PrometheusRule contains the alerting and recording rules that you would normally place in a Prometheus rule file.

    For a more fine-grained application of PrometheusRules within your cluster, the ruleSelector field on a Prometheus resource allows you to select which PrometheusRules should be loaded onto Prometheus based on the labels attached to the PrometheusRules resources.

    An example PrometheusRule is on this page.

    Alertmanager Config​

    For an example configuration, refer to this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/monitoring-v2-configuration/helm-chart-options.html b/v2.5/reference-guides/monitoring-v2-configuration/helm-chart-options.html index 05027a3699f..af6cf35de09 100644 --- a/v2.5/reference-guides/monitoring-v2-configuration/helm-chart-options.html +++ b/v2.5/reference-guides/monitoring-v2-configuration/helm-chart-options.html @@ -5,13 +5,13 @@ Helm Chart Options | Rancher Manager - +
    Version: v2.5

    Helm Chart Options

    Configuring Resource Limits and Requests​

    The resource requests and limits can be configured when installing rancher-monitoring.

    The default values are in the values.yaml in the rancher-monitoring Helm chart.

    The default values in the table below are the minimum required resource limits and requests.

    Resource NameMemory LimitCPU LimitMemory RequestCPU Request
    alertmanager500Mi1000m100Mi100m
    grafana200Mi200m100Mi100m
    kube-state-metrics subchart200Mi100m130Mi100m
    prometheus-node-exporter subchart50Mi200m30Mi100m
    prometheusOperator500Mi200m100Mi100m
    prometheus2500Mi1000m1750Mi750m
    Total3950Mi2700m2210Mi1250m

    At least 50Gi storage is recommended.

    Trusted CA for Notifiers​

    If you need to add a trusted CA to your notifier, follow these steps:

    1. Create the cattle-monitoring-system namespace.
    2. Add your trusted CA secret to the cattle-monitoring-system namespace.
    3. Deploy or upgrade the rancher-monitoring Helm chart. In the chart options, reference the secret in Alerting > Additional Secrets.

    Result: The default Alertmanager custom resource will have access to your trusted CA.

    Additional Scrape Configurations​

    If the scrape configuration you want cannot be specified via a ServiceMonitor or PodMonitor at the moment, you can provide an additionalScrapeConfigSecret on deploying or upgrading rancher-monitoring.

    A scrape_config section specifies a set of targets and parameters describing how to scrape them. In the general case, one scrape configuration specifies a single job.

    An example of where this might be used is with Istio. For more information, see this section.

    Configuring Applications Packaged within Monitoring v2​

    We deploy kube-state-metrics and node-exporter with monitoring v2. Node exporter are deployed as DaemonSets. In the monitoring v2 helm chart, in the values.yaml, each of the things are deployed as sub charts.

    We also deploy grafana which is not managed by prometheus.

    If you look at what the helm chart is doing like in kube-state-metrics, there are plenty more values that you can set that aren’t exposed in the top level chart.

    But in the top level chart you can add values that override values that exist in the sub chart.

    Increase the Replicas of Alertmanager​

    As part of the chart deployment options, you can opt to increase the number of replicas of the Alertmanager deployed onto your cluster. The replicas can all be managed using the same underlying Alertmanager Config Secret. For more information on the Alertmanager Config Secret, refer to this section

    Configuring the Namespace for a Persistent Grafana Dashboard​

    To specify that you would like Grafana to watch for ConfigMaps across all namespaces, set this value in the rancher-monitoring Helm chart:

    grafana.sidecar.dashboards.searchNamespace=ALL

    Note that the RBAC roles exposed by the Monitoring chart to add Grafana Dashboards are still restricted to giving permissions for users to add dashboards in the namespace defined in grafana.dashboards.namespace, which defaults to cattle-dashboards.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/monitoring-v2-configuration/receivers.html b/v2.5/reference-guides/monitoring-v2-configuration/receivers.html index 4d201dc1528..7b90c5992f5 100644 --- a/v2.5/reference-guides/monitoring-v2-configuration/receivers.html +++ b/v2.5/reference-guides/monitoring-v2-configuration/receivers.html @@ -5,13 +5,13 @@ Receiver Configuration | Rancher Manager - +
    Version: v2.5

    Receiver Configuration

    The Alertmanager Config Secret contains the configuration of an Alertmanager instance that sends out notifications based on alerts it receives from Prometheus.

    This section assumes familiarity with how monitoring components work together. For more information about Alertmanager, see this section.

    Creating Receivers in the Rancher UI​

    Available as of v2.5.4

    Prerequisites:

    • The monitoring application needs to be installed.
    • If you configured monitoring with an existing Alertmanager Secret, it must have a format that is supported by Rancher's UI. Otherwise you will only be able to make changes based on modifying the Alertmanager Secret directly. Note: We are continuing to make enhancements to what kinds of Alertmanager Configurations we can support using the Routes and Receivers UI, so please file an issue if you have a request for a feature enhancement.

    To create notification receivers in the Rancher UI,

    1. Click Cluster Explorer > Monitoring and click Receiver.
    2. Enter a name for the receiver.
    3. Configure one or more providers for the receiver. For help filling out the forms, refer to the configuration options below.
    4. Click Create.

    Result: Alerts can be configured to send notifications to the receiver(s).

    Receiver Configuration​

    The notification integrations are configured with the receiver, which is explained in the Prometheus documentation.

    Native vs. Non-native Receivers​

    By default, AlertManager provides native integration with some receivers, which are listed in this section. All natively supported receivers are configurable through the Rancher UI.

    For notification mechanisms not natively supported by AlertManager, integration is achieved using the webhook receiver. A list of third-party drivers providing such integrations can be found here. Access to these drivers, and their associated integrations, is provided through the Alerting Drivers app. Once enabled, configuring non-native receivers can also be done through the Rancher UI.

    Currently the Rancher Alerting Drivers app provides access to the following integrations:

    Changes in Rancher v2.5.8​

    Rancher v2.5.8 added Microsoft Teams and SMS as configurable receivers in the Rancher UI.

    Changes in Rancher v2.5.4​

    Rancher v2.5.4 introduced the capability to configure receivers by filling out forms in the Rancher UI.

    The following types of receivers can be configured in the Rancher UI:

    The custom receiver option can be used to configure any receiver in YAML that cannot be configured by filling out the other forms in the Rancher UI.

    Slack​

    FieldTypeDescription
    URLStringEnter your Slack webhook URL. For instructions to create a Slack webhook, see the Slack documentation.
    Default ChannelStringEnter the name of the channel that you want to send alert notifications in the following format: #<channelname>.
    Proxy URLStringProxy for the webhook notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Email​

    FieldTypeDescription
    Default Recipient AddressStringThe email address that will receive notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    SMTP options:

    FieldTypeDescription
    SenderStringEnter an email address available on your SMTP mail server that you want to send the notification from.
    HostStringEnter the IP address or hostname for your SMTP server. Example: smtp.email.com.
    Use TLSBoolUse TLS for encryption.
    UsernameStringEnter a username to authenticate with the SMTP server.
    PasswordStringEnter a password to authenticate with the SMTP server.

    PagerDuty​

    FieldTypeDescription
    Integration TypeStringEvents API v2 or Prometheus.
    Default Integration KeyStringFor instructions to get an integration key, see the PagerDuty documentation.
    Proxy URLStringProxy for the PagerDuty notifications.
    Enable Send Resolved AlertsBoolWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Opsgenie​

    FieldDescription
    API KeyFor instructions to get an API key, refer to the Opsgenie documentation.
    Proxy URLProxy for the Opsgenie notifications.
    Enable Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Opsgenie Responders:

    FieldTypeDescription
    TypeStringSchedule, Team, User, or Escalation. For more information on alert responders, refer to the Opsgenie documentation.
    Send ToStringId, Name, or Username of the Opsgenie recipient.

    Webhook​

    FieldDescription
    URLWebhook URL for the app of your choice.
    Proxy URLProxy for the webhook notification.
    Enable Send Resolved AlertsWhether to send a follow-up notification if an alert has been resolved (e.g. [Resolved] High CPU Usage).

    Custom​

    The YAML provided here will be directly appended to your receiver within the Alertmanager Config Secret.

    Teams​

    Enabling the Teams Receiver for Rancher Managed Clusters​

    The Teams receiver is not a native receiver and must be enabled before it can be used. You can enable the Teams receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the Teams option selected.

    1. In the Rancher UI, go to the cluster where you want to install rancher-alerting-drivers and click Cluster Explorer.
    2. Click Apps.
    3. Click the Alerting Drivers app.
    4. Click the Helm Deploy Options tab
    5. Select the Teams option and click Install.
    6. Take note of the namespace used as it will be required in a later step.

    Configure the Teams Receiver​

    The Teams receiver can be configured by updating its ConfigMap. For example, the following is a minimal Teams receiver configuration.

    [Microsoft Teams]
    teams-instance-1: https://your-teams-webhook-url

    When configuration is complete, add the receiver using the steps in this section.

    Use the example below as the URL where:

    • ns-1 is replaced with the namespace where the rancher-alerting-drivers app is installed
    url: http://rancher-alerting-drivers-prom2teams.ns-1.svc:8089/v2/teams-instance-1

    SMS​

    Enabling the SMS Receiver for Rancher Managed Clusters​

    The SMS receiver is not a native receiver and must be enabled before it can be used. You can enable the SMS receiver for a Rancher managed cluster by going to the Apps page and installing the rancher-alerting-drivers app with the SMS option selected.

    1. In the Rancher UI, go to the cluster where you want to install rancher-alerting-drivers and click Cluster Explorer.
    2. Click Apps.
    3. Click the Alerting Drivers app.
    4. Click the Helm Deploy Options tab
    5. Select the SMS option and click Install.
    6. Take note of the namespace used as it will be required in a later step.

    Configure the SMS Receiver​

    The SMS receiver can be configured by updating its ConfigMap. For example, the following is a minimal SMS receiver configuration.

    providers:
      telegram:
        token: 'your-token-from-telegram'

    receivers:
    - name: 'telegram-receiver-1'
      provider: 'telegram'
      to:
        - '123456789'

    When configuration is complete, add the receiver using the steps in this section.

    Use the example below as the name and URL, where:

    • the name assigned to the receiver, e.g. telegram-receiver-1, must match the name in the receivers.name field in the ConfigMap, e.g. telegram-receiver-1
    • ns-1 in the URL is replaced with the namespace where the rancher-alerting-drivers app is installed
    name: telegram-receiver-1
    url http://rancher-alerting-drivers-sachet.ns-1.svc:9876/alert

    Configuring Multiple Receivers​

    By editing the forms in the Rancher UI, you can set up a Receiver resource with all the information Alertmanager needs to send alerts to your notification system.

    It is also possible to send alerts to multiple notification systems. One way is to configure the Receiver using custom YAML, in which case you can add the configuration for multiple notification systems, as long as you are sure that both systems should receive the same messages.

    You can also set up multiple receivers by using the continue option for a route, so that the alerts sent to a receiver continue being evaluated in the next level of the routing tree, which could contain another receiver.

    Example Alertmanager Configs​

    Slack​

    To set up notifications via Slack, the following Alertmanager Config YAML can be placed into the alertmanager.yaml key of the Alertmanager Config Secret, where the api_url should be updated to use your Webhook URL from Slack:

    route:
      group_by: ['job']
      group_wait: 30s
      group_interval: 5m
      repeat_interval: 3h
      receiver: 'slack-notifications'
    receivers:
    - name: 'slack-notifications'
      slack_configs:
      - send_resolved: true
        text: '{{ template "slack.rancher.text" . }}'
        api_url: <user-provided slack webhook url here>
    templates:
    - /etc/alertmanager/config/*.tmpl

    PagerDuty​

    To set up notifications via PagerDuty, use the example below from the PagerDuty documentation as a guideline. This example sets up a route that captures alerts for a database service and sends them to a receiver linked to a service that will directly notify the DBAs in PagerDuty, while all other alerts will be directed to a default receiver with a different PagerDuty integration key.

    The following Alertmanager Config YAML can be placed into the alertmanager.yaml key of the Alertmanager Config Secret. The service_key should be updated to use your PagerDuty integration key and can be found as per the "Integrating with Global Event Routing" section of the PagerDuty documentation. For the full list of configuration options, refer to the Prometheus documentation.

    route:
     group_by: [cluster]
     receiver: 'pagerduty-notifications'
     group_interval: 5m
     routes:
      - match:
          service: database
        receiver: 'database-notifcations'

    receivers:
    - name: 'pagerduty-notifications'
      pagerduty_configs:
      - service_key: 'primary-integration-key'

    - name: 'database-notifcations'
      pagerduty_configs:
      - service_key: 'database-integration-key'

    Example Route Config for CIS Scan Alerts​

    While configuring the routes for rancher-cis-benchmark alerts, you can specify the matching using the key-value pair job: rancher-cis-scan.

    For example, the following example route configuration could be used with a Slack receiver named test-cis:

    spec:
      receiver: test-cis
      group_by:
    #    - string
      group_wait: 30s
      group_interval: 30s
      repeat_interval: 30s
      match:
        job: rancher-cis-scan
    #    key: string
      match_re:
        {}
    #    key: string

    For more information on enabling alerting for rancher-cis-benchmark, see this section.

    Trusted CA for Notifiers​

    If you need to add a trusted CA to your notifier, follow the steps in this section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/monitoring-v2-configuration/routes.html b/v2.5/reference-guides/monitoring-v2-configuration/routes.html index 449cff9e46f..522a71ab5c7 100644 --- a/v2.5/reference-guides/monitoring-v2-configuration/routes.html +++ b/v2.5/reference-guides/monitoring-v2-configuration/routes.html @@ -5,13 +5,13 @@ Route Configuration | Rancher Manager - +
    Version: v2.5

    Route Configuration

    The route configuration is the section of the Alertmanager custom resource that controls how the alerts fired by Prometheus are grouped and filtered before they reach the receiver.

    When a Route is changed, the Prometheus Operator regenerates the Alertmanager custom resource to reflect the changes.

    For more information about configuring routes, refer to the official Alertmanager documentation.

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    Route Restrictions​

    Alertmanager proxies alerts for Prometheus based on its receivers and a routing tree that filters alerts to certain receivers based on labels.

    Alerting drivers proxy alerts for Alertmanager to non-native receivers, such as Microsoft Teams and SMS.

    In the Rancher UI for configuring routes and receivers, you can configure routing trees with one root and then a depth of one more level, for a tree with a depth of two. But if you use a continue route when configuring Alertmanager directly, you can make the tree deeper.

    Each receiver is for one or more notification providers. So if you know that every alert for Slack should also go to PagerDuty, you can configure both in the same receiver.

    Route Configuration​

    Note on Labels and Annotations​

    Labels should be used for identifying information that can affect the routing of notifications. Identifying information about the alert could consist of a container name, or the name of the team that should be notified.

    Annotations should be used for information that does not affect who receives the alert, such as a runbook url or error message.

    Receiver​

    The route needs to refer to a receiver that has already been configured.

    Grouping​

    FieldDefaultDescription
    Group ByN/aThe labels by which incoming alerts are grouped together. For example, [ group_by: '[' <labelname>, ... ']' ] Multiple alerts coming in for labels such as cluster=A and alertname=LatencyHigh can be batched into a single group. To aggregate by all possible labels, use the special value '...' as the sole label name, for example: group_by: ['...'] Grouping by ... effectively disables aggregation entirely, passing through all alerts as-is. This is unlikely to be what you want, unless you have a very low alert volume or your upstream notification system performs its own grouping.
    Group Wait30sHow long to wait to buffer alerts of the same group before sending initially.
    Group Interval5mHow long to wait before sending an alert that has been added to a group of alerts for which an initial notification has already been sent.
    Repeat Interval4hHow long to wait before re-sending a given alert that has already been sent.

    Matching​

    The Match field refers to a set of equality matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs to the Rancher UI, they correspond to the YAML in this format:

    match:
      [ <labelname>: <labelvalue>, ... ]

    The Match Regex field refers to a set of regex-matchers used to identify which alerts to send to a given Route based on labels defined on that alert. When you add key-value pairs in the Rancher UI, they correspond to the YAML in this format:

    match_re:
      [ <labelname>: <regex>, ... ]
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html b/v2.5/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html index 38b12cb65e0..dbe07855410 100644 --- a/v2.5/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html +++ b/v2.5/reference-guides/monitoring-v2-configuration/servicemonitors-and-podmonitors.html @@ -5,13 +5,13 @@ ServiceMonitor and PodMonitor Configuration | Rancher Manager - +
    Version: v2.5

    ServiceMonitor and PodMonitor Configuration

    ServiceMonitors and PodMonitors are both pseudo-CRDs that map the scrape configuration of the Prometheus custom resource.

    These configuration objects declaratively specify the endpoints that Prometheus will scrape metrics from.

    ServiceMonitors are more commonly used than PodMonitors, and we recommend them for most use cases.

    This section assumes familiarity with how monitoring components work together. For more information, see this section.

    ServiceMonitors​

    This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how groups of Kubernetes services should be monitored.

    When a ServiceMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the ServiceMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the ServiceMonitor.

    Any Services in your cluster that match the labels located within the ServiceMonitor selector field will be monitored based on the endpoints specified on the ServiceMonitor. For more information on what fields can be specified, please look at the spec provided by Prometheus Operator.

    For more information about how ServiceMonitors work, refer to the Prometheus Operator documentation.

    PodMonitors​

    This pseudo-CRD maps to a section of the Prometheus custom resource configuration. It declaratively specifies how group of pods should be monitored.

    When a PodMonitor is created, the Prometheus Operator updates the Prometheus scrape configuration to include the PodMonitor configuration. Then Prometheus begins scraping metrics from the endpoint defined in the PodMonitor.

    Any Pods in your cluster that match the labels located within the PodMonitor selector field will be monitored based on the podMetricsEndpoints specified on the PodMonitor. For more information on what fields can be specified, please look at the spec provided by Prometheus Operator.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/pipelines/concepts.html b/v2.5/reference-guides/pipelines/concepts.html index 0081f570165..75ab489c017 100644 --- a/v2.5/reference-guides/pipelines/concepts.html +++ b/v2.5/reference-guides/pipelines/concepts.html @@ -5,13 +5,13 @@ Concepts | Rancher Manager - +
    Version: v2.5

    Concepts

    The purpose of this page is to explain common concepts and terminology related to pipelines.

    • Pipeline:

      A pipeline is a software delivery process that is broken into different stages and steps. Setting up a pipeline can help developers deliver new software as quickly and efficiently as possible. Within Rancher, you can configure pipelines for each of your Rancher projects. A pipeline is based on a specific repository. It defines the process to build, test, and deploy your code. Rancher uses the pipeline as code model. Pipeline configuration is represented as a pipeline file in the source code repository, using the file name .rancher-pipeline.yml or .rancher-pipeline.yaml.

    • Stages:

      A pipeline stage consists of multiple steps. Stages are executed in the order defined in the pipeline file. The steps in a stage are executed concurrently. A stage starts when all steps in the former stage finish without failure.

    • Steps:

      A pipeline step is executed inside a specified stage. A step fails if it exits with a code other than 0. If a step exits with this failure code, the entire pipeline fails and terminates.

    • Workspace:

      The workspace is the working directory shared by all pipeline steps. In the beginning of a pipeline, source code is checked out to the workspace. The command for every step bootstraps in the workspace. During a pipeline execution, the artifacts from a previous step will be available in future steps. The working directory is an ephemeral volume and will be cleaned out with the executor pod when a pipeline execution is finished.

    Typically, pipeline stages include:

    • Build:

      Each time code is checked into your repository, the pipeline automatically clones the repo and builds a new iteration of your software. Throughout this process, the software is typically reviewed by automated tests.

    • Publish:

      After the build is completed, either a Docker image is built and published to a Docker registry or a catalog template is published.

    • Deploy:

      After the artifacts are published, you would release your application so users could start using the updated product.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/pipelines/configure-persistent-data.html b/v2.5/reference-guides/pipelines/configure-persistent-data.html index a9355c6c27f..aa8d63a6f72 100644 --- a/v2.5/reference-guides/pipelines/configure-persistent-data.html +++ b/v2.5/reference-guides/pipelines/configure-persistent-data.html @@ -5,13 +5,13 @@ Configuring Persistent Data for Pipeline Components | Rancher Manager - +
    Version: v2.5

    Configuring Persistent Data for Pipeline Components

    The pipelines' internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

    This section assumes that you understand how persistent storage works in Kubernetes. For more information, refer to the section on how storage works.

    Prerequisites (for both parts A and B):

    Persistent volumes must be available for the cluster.

    A. Configuring Persistent Data for Docker Registry​

    1. From the project that you're configuring a pipeline for, and click Resources > Workloads.

    2. Find the docker-registry workload and select ⋮ > Edit.

    3. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

      • Add Volume > Add a new persistent volume (claim)
      • Add Volume > Use an existing persistent volume (claim)

    4. Complete the form that displays to choose a persistent volume for the internal Docker registry.

      1. Enter a Name for the volume claim.
      2. Select a volume claim Source:
        • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
        • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
      3. From the Customize section, choose the read/write access for the volume.
      4. Click Define.

    5. From the Mount Point field, enter /var/lib/registry, which is the data storage path inside the Docker registry container.

    6. Click Upgrade.

    B. Configuring Persistent Data for Minio​

    1. From the project view, click Resources > Workloads. Find the minio workload and select ⋮ > Edit.

    2. Scroll to the Volumes section and expand it. Make one of the following selections from the Add Volume menu, which is near the bottom of the section:

      • Add Volume > Add a new persistent volume (claim)
      • Add Volume > Use an existing persistent volume (claim)

    3. Complete the form that displays to choose a persistent volume for the internal Docker registry.

      1. Enter a Name for the volume claim.
      2. Select a volume claim Source:
        • If you select Use a Storage Class to provision a new persistent volume, select a storage class and enter a Capacity.
        • If you select Use an existing persistent volume, choose a Persistent Volume from the drop-down.
      3. From the Customize section, choose the read/write access for the volume.
      4. Click Define.

    4. From the Mount Point field, enter /data, which is the data storage path inside the Minio container.

    5. Click Upgrade.

    Result: Persistent storage is configured for your pipeline components.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/pipelines/example-repositories.html b/v2.5/reference-guides/pipelines/example-repositories.html index 1d240465698..ecd033396b4 100644 --- a/v2.5/reference-guides/pipelines/example-repositories.html +++ b/v2.5/reference-guides/pipelines/example-repositories.html @@ -5,13 +5,13 @@ Example Repositories | Rancher Manager - +
    Version: v2.5

    Example Repositories

    Rancher ships with several example repositories that you can use to familiarize yourself with pipelines. We recommend configuring and testing the example repository that most resembles your environment before using pipelines with your own repositories in a production environment. Use this example repository as a sandbox for repo configuration, build demonstration, etc. Rancher includes example repositories for:

    • Go
    • Maven
    • php

    Note: The example repositories are only available if you have not configured a version control provider.

    To start using these example repositories,

    1. Enable the example repositories
    2. View the example pipeline
    3. Run the example pipeline

    1. Enable the Example Repositories​

    By default, the example pipeline repositories are disabled. Enable one (or more) to test out the pipeline feature and see how it works.

    1. From the Global view, navigate to the project that you want to test out pipelines.

    2. Click Resources > Pipelines.

    3. Click Configure Repositories.

      Step Result: A list of example repositories displays.

      Note: Example repositories only display if you haven't fetched your own repos.

    4. Click Enable for one of the example repos (e.g., https://github.com/rancher/pipeline-example-go.git). Then click Done.

    Results:

    • The example repository is enabled to work with a pipeline is available in the Pipeline tab.

    • The following workloads are deployed to a new namespace:

      • docker-registry
      • jenkins
      • minio

    2. View the Example Pipeline​

    After enabling an example repository, review the pipeline to see how it is set up.

    1. From the Global view, navigate to the project that you want to test out pipelines.

    2. Click Resources > Pipelines.

    3. Find the example repository, select the vertical ⋮. There are two ways to view the pipeline:

    • Rancher UI: Click on Edit Config to view the stages and steps of the pipeline.
    • YAML: Click on View/Edit YAML to view the ./rancher-pipeline.yml file.

    3. Run the Example Pipeline​

    After enabling an example repository, run the pipeline to see how it works.

    1. From the Global view, navigate to the project that you want to test out pipelines.

    2. Click Resources > Pipelines.

    3. Find the example repository, select the vertical ⋮ > Run.

      Note: When you run a pipeline the first time, it takes a few minutes to pull relevant images and provision necessary pipeline components.

    Result: The pipeline runs. You can see the results in the logs.

    What's Next?​

    For detailed information about setting up your own pipeline for your repository, configure a version control provider, enable a repository and finally configure your pipeline.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/pipelines/example-yaml.html b/v2.5/reference-guides/pipelines/example-yaml.html index 5620dd84737..8a907f87e43 100644 --- a/v2.5/reference-guides/pipelines/example-yaml.html +++ b/v2.5/reference-guides/pipelines/example-yaml.html @@ -5,13 +5,13 @@ Example YAML File | Rancher Manager - +
    Version: v2.5

    Example YAML File

    Pipelines can be configured either through the UI or using a yaml file in the repository, i.e. .rancher-pipeline.yml or .rancher-pipeline.yaml.

    In the pipeline configuration reference, we provide examples of how to configure each feature using the Rancher UI or using YAML configuration.

    Below is a full example rancher-pipeline.yml for those who want to jump right in.

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${FIRST_KEY} && echo ${ALIAS_ENV}
          # Set environment variables in container for the step
          env:
            FIRST_KEY: VALUE
            SECOND_KEY: VALUE2
          # Set environment variables from project secrets
          envFrom:
          - sourceName: my-secret
            sourceKey: secret-key
            targetKey: ALIAS_ENV
        - runScriptConfig:
            image: busybox
            shellScript: date -R
          # Conditions for steps
          when:
            branch: [ master, dev ]
            event: push
      - name: Publish my image
        steps:
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: rancher/rancher:v2.0.0
            # Optionally push to remote registry
            pushRemote: true
            registry: reg.example.com
      - name: Deploy some workloads
        steps:
        - applyYamlConfig:
            path: ./deployment.yaml
    # branch conditions for the pipeline
    branch:
      include: [ master, feature/*]
      exclude: [ dev ]
    # timeout in minutes
    timeout: 30
    notification:
      recipients:
      - # Recipient
        recipient: "#mychannel"
        # ID of Notifier
        notifier: "c-wdcsr:n-c9pg7"
      - recipient: "test@example.com"
        notifier: "c-wdcsr:n-lkrhd"
      # Select which statuses you want the notification to be sent
      condition: ["Failed", "Success", "Changed"]
      # Ability to override the default message (Optional)
      message: "my-message"
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/pipelines/pipeline-configuration.html b/v2.5/reference-guides/pipelines/pipeline-configuration.html index b80cbf78bce..61e666dcfda 100644 --- a/v2.5/reference-guides/pipelines/pipeline-configuration.html +++ b/v2.5/reference-guides/pipelines/pipeline-configuration.html @@ -5,13 +5,13 @@ Pipeline Configuration Reference | Rancher Manager - +
    Version: v2.5

    Pipeline Configuration Reference

    In this section, you'll learn how to configure pipelines.

    Step Types​

    Within each stage, you can add as many steps as you'd like. When there are multiple steps in one stage, they run concurrently.

    Step types include:

    Configuring Steps By UI​

    If you haven't added any stages, click Configure pipeline for this branch to configure the pipeline through the UI.

    1. Add stages to your pipeline execution by clicking Add Stage.

      1. Enter a Name for each stage of your pipeline.
      2. For each stage, you can configure trigger rules by clicking on Show Advanced Options. Note: this can always be updated at a later time.

    2. After you've created a stage, start adding steps by clicking Add a Step. You can add multiple steps to each stage.

    Configuring Steps by YAML​

    For each stage, you can add multiple steps. Read more about each step type and the advanced options to get all the details on how to configure the YAML. This is only a small example of how to have multiple stages with a singular step in each stage.

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
          - runScriptConfig:
              image: busybox
              shellScript: date -R
      - name: Publish my image
        steps:
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: rancher/rancher:v2.0.0
            # Optionally push to remote registry
            pushRemote: true
            registry: reg.example.com

    Step Type: Run Script​

    The Run Script step executes arbitrary commands in the workspace inside a specified container. You can use it to build, test and do more, given whatever utilities the base image provides. For your convenience, you can use variables to refer to metadata of a pipeline execution. Please refer to the pipeline variable substitution reference for the list of available variables.

    Configuring Script by UI​

    1. From the Step Type drop-down, choose Run Script and fill in the form.

    2. Click Add.

    Configuring Script by YAML​

    # example
    stages:
    - name: Build something
      steps:
      - runScriptConfig:
          image: golang
          shellScript: go build

    Step Type: Build and Publish Images​

    The Build and Publish Image step builds and publishes a Docker image. This process requires a Dockerfile in your source code's repository to complete successfully.

    The option to publish an image to an insecure registry is not exposed in the UI, but you can specify an environment variable in the YAML that allows you to publish an image insecurely.

    Configuring Building and Publishing Images by UI​

    1. From the Step Type drop-down, choose Build and Publish.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      Dockerfile PathThe relative path to the Dockerfile in the source code repo. By default, this path is ./Dockerfile, which assumes the Dockerfile is in the root directory. You can set it to other paths in different use cases (./path/to/myDockerfile for example).
      Image NameThe image name in name:tag format. The registry address is not required. For example, to build example.com/repo/my-image:dev, enter repo/my-image:dev.
      Push image to remote repositoryAn option to set the registry that publishes the image that's built. To use this option, enable it and choose a registry from the drop-down. If this option is disabled, the image is pushed to the internal registry.
      Build Context

      (Show advanced options)      		By default, the root directory of the source code (.). For more details, see the Docker build command documentation.

    Configuring Building and Publishing Images by YAML​

    You can use specific arguments for Docker daemon and the build. They are not exposed in the UI, but they are available in pipeline YAML format, as indicated in the example below. Available environment variables include:

    Variable NameDescription
    PLUGIN_DRY_RUNDisable docker push
    PLUGIN_DEBUGDocker daemon executes in debug mode
    PLUGIN_MIRRORDocker daemon registry mirror
    PLUGIN_INSECUREDocker daemon allows insecure registries
    PLUGIN_BUILD_ARGSDocker build args, a comma separated list

    # This example shows an environment variable being used
    # in the Publish Image step. This variable allows you to
    # publish an image to an insecure registry:

    stages:
    - name: Publish Image
      steps:
      - publishImageConfig:
          dockerfilePath: ./Dockerfile
          buildContext: .
          tag: repo/app:v1
          pushRemote: true
          registry: example.com
        env:
          PLUGIN_INSECURE: "true"

    Step Type: Publish Catalog Template​

    The Publish Catalog Template step publishes a version of a catalog app template (i.e. Helm chart) to a git hosted chart repository. It generates a git commit and pushes it to your chart repository. This process requires a chart folder in your source code's repository and a pre-configured secret in the dedicated pipeline namespace to complete successfully. Any variables in the pipeline variable substitution reference is supported for any file in the chart folder.

    Configuring Publishing a Catalog Template by UI​

    1. From the Step Type drop-down, choose Publish Catalog Template.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      Chart FolderThe relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
      Catalog Template NameThe name of the template. For example, wordpress.
      Catalog Template VersionThe version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
      ProtocolYou can choose to publish via HTTP(S) or SSH protocol.
      SecretThe secret that stores your Git credentials. You need to create a secret in dedicated pipeline namespace in the project before adding this step. If you use HTTP(S) protocol, store Git username and password in USERNAME and PASSWORD key of the secret. If you use SSH protocol, store Git deploy key in DEPLOY_KEY key of the secret. After the secret is created, select it in this option.
      Git URLThe Git URL of the chart repository that the template will be published to.
      Git BranchThe Git branch of the chart repository that the template will be published to.
      Author NameThe author name used in the commit message.
      Author EmailThe author email used in the commit message.

    Configuring Publishing a Catalog Template by YAML​

    You can add Publish Catalog Template steps directly in the .rancher-pipeline.yml file.

    Under the steps section, add a step with publishCatalogConfig. You will provide the following information:

    • Path: The relative path to the chart folder in the source code repo, where the Chart.yaml file is located.
    • CatalogTemplate: The name of the template.
    • Version: The version of the template you want to publish, it should be consistent with the version defined in the Chart.yaml file.
    • GitUrl: The git URL of the chart repository that the template will be published to.
    • GitBranch: The git branch of the chart repository that the template will be published to.
    • GitAuthor: The author name used in the commit message.
    • GitEmail: The author email used in the commit message.
    • Credentials: You should provide Git credentials by referencing secrets in dedicated pipeline namespace. If you publish via SSH protocol, inject your deploy key to the DEPLOY_KEY environment variable. If you publish via HTTP(S) protocol, inject your username and password to USERNAME and PASSWORD environment variables.
    # example
    stages:
    - name: Publish Wordpress Template
      steps:
      - publishCatalogConfig:
          path: ./charts/wordpress/latest
          catalogTemplate: wordpress
          version: ${CICD_GIT_TAG}
          gitUrl: git@github.com:myrepo/charts.git
          gitBranch: master
          gitAuthor: example-user
          gitEmail: user@example.com
        envFrom:
        - sourceName: publish-keys
          sourceKey: DEPLOY_KEY

    Step Type: Deploy YAML​

    This step deploys arbitrary Kubernetes resources to the project. This deployment requires a Kubernetes manifest file to be present in the source code repository. Pipeline variable substitution is supported in the manifest file. You can view an example file at GitHub. Please refer to the pipeline variable substitution reference for the list of available variables.

    Configure Deploying YAML by UI​

    1. From the Step Type drop-down, choose Deploy YAML and fill in the form.

    2. Enter the YAML Path, which is the path to the manifest file in the source code.

    3. Click Add.

    Configure Deploying YAML by YAML​

    # example
    stages:
    - name: Deploy
      steps:
      - applyYamlConfig:
          path: ./deployment.yaml

    Step Type :Deploy Catalog App​

    The Deploy Catalog App step deploys a catalog app in the project. It will install a new app if it is not present, or upgrade an existing one.

    Configure Deploying Catalog App by UI​

    1. From the Step Type drop-down, choose Deploy Catalog App.

    2. Fill in the rest of the form. Descriptions for each field are listed below. When you're done, click Add.

      FieldDescription
      CatalogThe catalog from which the app template will be used.
      Template NameThe name of the app template. For example, wordpress.
      Template VersionThe version of the app template you want to deploy.
      NamespaceThe target namespace where you want to deploy the app.
      App NameThe name of the app you want to deploy.
      AnswersKey-value pairs of answers used to deploy the app.

    Configure Deploying Catalog App by YAML​

    You can add Deploy Catalog App steps directly in the .rancher-pipeline.yml file.

    Under the steps section, add a step with applyAppConfig. You will provide the following information:

    • CatalogTemplate: The ID of the template. This can be found by clicking Launch app and selecting View details for the app. It is the last part of the URL.
    • Version: The version of the template you want to deploy.
    • Answers: Key-value pairs of answers used to deploy the app.
    • Name: The name of the app you want to deploy.
    • TargetNamespace: The target namespace where you want to deploy the app.
    # example
    stages:
    - name: Deploy App
      steps:
      - applyAppConfig:
          catalogTemplate: cattle-global-data:library-mysql
          version: 0.3.8
          answers:
            persistence.enabled: "false"
          name: testmysql
          targetNamespace: test

    Timeouts​

    By default, each pipeline execution has a timeout of 60 minutes. If the pipeline execution cannot complete within its timeout period, the pipeline is aborted.

    Configuring Timeouts by UI​

    Enter a new value in the Timeout field.

    Configuring Timeouts by YAML​

    In the timeout section, enter the timeout value in minutes.

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
    # timeout in minutes
    timeout: 30

    Notifications​

    You can enable notifications to any notifiers based on the build status of a pipeline. Before enabling notifications, Rancher recommends setting up notifiers so it will be easy to add recipients immediately.

    Configuring Notifications by UI​

    1. Within the Notification section, turn on notifications by clicking Enable.

    2. Select the conditions for the notification. You can select to get a notification for the following statuses: Failed, Success, Changed. For example, if you want to receive notifications when an execution fails, select Failed.

    3. If you don't have any existing notifiers, Rancher will provide a warning that no notifiers are set up and provide a link to be able to go to the notifiers page. Follow the instructions to add a notifier. If you already have notifiers, you can add them to the notification by clicking the Add Recipient button.

      Note: Notifiers are configured at a cluster level and require a different level of permissions.

    4. For each recipient, select which notifier type from the dropdown. Based on the type of notifier, you can use the default recipient or override the recipient with a different one. For example, if you have a notifier for Slack, you can update which channel to send the notification to. You can add additional notifiers by clicking Add Recipient.

    Configuring Notifications by YAML​

    In the notification section, you will provide the following information:

    • Recipients: This will be the list of notifiers/recipients that will receive the notification.
      • Notifier: The ID of the notifier. This can be found by finding the notifier and selecting View in API to get the ID.
      • Recipient: Depending on the type of the notifier, the "default recipient" can be used or you can override this with a different recipient. For example, when configuring a slack notifier, you select a channel as your default recipient, but if you wanted to send notifications to a different channel, you can select a different recipient.
    • Condition: Select which conditions of when you want the notification to be sent.
    • Message (Optional): If you want to change the default notification message, you can edit this in the yaml. Note: This option is not available in the UI.
    # Example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
    notification:
      recipients:
      - # Recipient
        recipient: "#mychannel"
        # ID of Notifier
        notifier: "c-wdcsr:n-c9pg7"
      - recipient: "test@example.com"
        notifier: "c-wdcsr:n-lkrhd"
      # Select which statuses you want the notification to be sent
      condition: ["Failed", "Success", "Changed"]
      # Ability to override the default message (Optional)
      message: "my-message"

    Triggers and Trigger Rules​

    After you configure a pipeline, you can trigger it using different methods:

    • Manually:

      After you configure a pipeline, you can trigger a build using the latest CI definition from Rancher UI. When a pipeline execution is triggered, Rancher dynamically provisions a Kubernetes pod to run your CI tasks and then remove it upon completion.

    • Automatically:

      When you enable a repository for a pipeline, webhooks are automatically added to the version control system. When project users interact with the repo by pushing code, opening pull requests, or creating a tag, the version control system sends a webhook to Rancher Server, triggering a pipeline execution.

      To use this automation, webhook management permission is required for the repository. Therefore, when users authenticate and fetch their repositories, only those on which they have webhook management permission will be shown.

    Trigger rules can be created to have fine-grained control of pipeline executions in your pipeline configuration. Trigger rules come in two types:

    • Run this when: This type of rule starts the pipeline, stage, or step when a trigger explicitly occurs.

    • Do Not Run this when: This type of rule skips the pipeline, stage, or step when a trigger explicitly occurs.

    If all conditions evaluate to true, then the pipeline/stage/step is executed. Otherwise it is skipped. When a pipeline is skipped, none of the pipeline is executed. When a stage/step is skipped, it is considered successful and follow-up stages/steps continue to run.

    Wildcard character (*) expansion is supported in branch conditions.

    Configuring Pipeline Triggers​

    1. From the Global view, navigate to the project that you want to configure a pipeline trigger rule.

    2. Click Resources > Pipelines.

    3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    4. Click on Show Advanced Options.

    5. In the Trigger Rules section, configure rules to run or skip the pipeline.

      1. Click Add Rule. In the Value field, enter the name of the branch that triggers the pipeline.

      2. Optional: Add more branches that trigger a build.

    6. Click Done.

    Configuring Stage Triggers​

    1. From the Global view, navigate to the project that you want to configure a stage trigger rule.

    2. Click Resources > Pipelines.

    3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    4. Find the stage that you want to manage trigger rules, click the Edit icon for that stage.

    5. Click Show advanced options.

    6. In the Trigger Rules section, configure rules to run or skip the stage.

      1. Click Add Rule.

      2. Choose the Type that triggers the stage and enter a value.

        TypeValue
        BranchThe name of the branch that triggers the stage.
        EventThe type of event that triggers the stage. Values are: Push, Pull Request, Tag

    7. Click Save.

    Configuring Step Triggers​

    1. From the Global view, navigate to the project that you want to configure a stage trigger rule.

    2. Click Resources > Pipelines.

    3. From the repository for which you want to manage trigger rules, select the vertical ⋮ > Edit Config.

    4. Find the step that you want to manage trigger rules, click the Edit icon for that step.

    5. Click Show advanced options.

    6. In the Trigger Rules section, configure rules to run or skip the step.

      1. Click Add Rule.

      2. Choose the Type that triggers the step and enter a value.

        TypeValue
        BranchThe name of the branch that triggers the step.
        EventThe type of event that triggers the step. Values are: Push, Pull Request, Tag

    7. Click Save.

    Configuring Triggers by YAML​

    # example
    stages:
      - name: Build something
        # Conditions for stages
        when:
          branch: master
          event: [ push, pull_request ]
        # Multiple steps run concurrently
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: date -R
          # Conditions for steps
          when:
            branch: [ master, dev ]
            event: push
    # branch conditions for the pipeline
    branch:
      include: [ master, feature/*]
      exclude: [ dev ]

    Environment Variables​

    When configuring a pipeline, certain step types allow you to use environment variables to configure the step's script.

    Configuring Environment Variables by UI​

    1. From the Global view, navigate to the project that you want to configure pipelines.

    2. Click Resources > Pipelines.

    3. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.

    4. Within one of the stages, find the step that you want to add an environment variable for, click the Edit icon.

    5. Click Show advanced options.

    6. Click Add Variable, and then enter a key and value in the fields that appear. Add more variables if needed.

    7. Add your environment variable(s) into either the script or file.

    8. Click Save.

    Configuring Environment Variables by YAML​

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${FIRST_KEY} && echo ${SECOND_KEY}
          env:
            FIRST_KEY: VALUE
            SECOND_KEY: VALUE2

    Secrets​

    If you need to use security-sensitive information in your pipeline scripts (like a password), you can pass them in using Kubernetes secrets.

    Prerequisite​

    Create a secret in the same project as your pipeline, or explicitly in the namespace where pipeline build pods run.


    Note: Secret injection is disabled on pull request events.

    Configuring Secrets by UI​

    1. From the Global view, navigate to the project that you want to configure pipelines.

    2. Click Resources > Pipelines.

    3. From the pipeline for which you want to edit build triggers, select ⋮ > Edit Config.

    4. Within one of the stages, find the step that you want to use a secret for, click the Edit icon.

    5. Click Show advanced options.

    6. Click Add From Secret. Select the secret file that you want to use. Then choose a key. Optionally, you can enter an alias for the key.

    7. Click Save.

    Configuring Secrets by YAML​

    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: echo ${ALIAS_ENV}
          # environment variables from project secrets
          envFrom:
          - sourceName: my-secret
            sourceKey: secret-key
            targetKey: ALIAS_ENV

    Pipeline Variable Substitution Reference​

    For your convenience, the following variables are available for your pipeline configuration scripts. During pipeline executions, these variables are replaced by metadata. You can reference them in the form of ${VAR_NAME}.

    Variable NameDescription
    CICD_GIT_REPO_NAMERepository name (Github organization omitted).
    CICD_GIT_URLURL of the Git repository.
    CICD_GIT_COMMITGit commit ID being executed.
    CICD_GIT_BRANCHGit branch of this event.
    CICD_GIT_REFGit reference specification of this event.
    CICD_GIT_TAGGit tag name, set on tag event.
    CICD_EVENTEvent that triggered the build (push, pull_request or tag).
    CICD_PIPELINE_IDRancher ID for the pipeline.
    CICD_EXECUTION_SEQUENCEBuild number of the pipeline.
    CICD_EXECUTION_IDCombination of {CICD_PIPELINE_ID}-{CICD_EXECUTION_SEQUENCE}.
    CICD_REGISTRYAddress for the Docker registry for the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step.
    CICD_IMAGEName of the image built from the previous publish image step, available in the Kubernetes manifest file of a Deploy YAML step. It does not contain the image tag.

    Example

    Global Pipeline Execution Settings​

    After configuring a version control provider, there are several options that can be configured globally on how pipelines are executed in Rancher. These settings can be edited by selecting Tools > Pipelines in the navigation bar.

    Executor Quota​

    Select the maximum number of pipeline executors. The executor quota decides how many builds can run simultaneously in the project. If the number of triggered builds exceeds the quota, subsequent builds will queue until a vacancy opens. By default, the quota is 2. A value of 0 or less removes the quota limit.

    Resource Quota for Executors​

    Configure compute resources for Jenkins agent containers. When a pipeline execution is triggered, a build pod is dynamically provisioned to run your CI tasks. Under the hood, A build pod consists of one Jenkins agent container and one container for each pipeline step. You can manage compute resources for every containers in the pod.

    Edit the Memory Reservation, Memory Limit, CPU Reservation or CPU Limit, then click Update Limit and Reservation.

    To configure compute resources for pipeline-step containers:

    You can configure compute resources for pipeline-step containers in the .rancher-pipeline.yml file.

    In a step, you will provide the following information:

    • CPU Reservation (CpuRequest): CPU request for the container of a pipeline step.
    • CPU Limit (CpuLimit): CPU limit for the container of a pipeline step.
    • Memory Reservation (MemoryRequest): Memory request for the container of a pipeline step.
    • Memory Limit (MemoryLimit): Memory limit for the container of a pipeline step.
    # example
    stages:
      - name: Build something
        steps:
        - runScriptConfig:
            image: busybox
            shellScript: ls
          cpuRequest: 100m
          cpuLimit: 1
          memoryRequest:100Mi
          memoryLimit: 1Gi
        - publishImageConfig:
            dockerfilePath: ./Dockerfile
            buildContext: .
            tag: repo/app:v1
          cpuRequest: 100m
          cpuLimit: 1
          memoryRequest:100Mi
          memoryLimit: 1Gi

    Note: Rancher sets default compute resources for pipeline steps except for Build and Publish Images and Run Script steps. You can override the default value by specifying compute resources in the same way.

    Custom CA​

    If you want to use a version control provider with a certificate from a custom/internal CA root, the CA root certificates need to be added as part of the version control provider configuration in order for the pipeline build pods to succeed.

    1. Click Edit cacerts.

    2. Paste in the CA root certificates and click Save cacerts.

    Result: Pipelines can be used and new pods will be able to work with the self-signed-certificate.

    Persistent Data for Pipeline Components​

    The internal Docker registry and the Minio workloads use ephemeral volumes by default. This default storage works out-of-the-box and makes testing easy, but you lose the build images and build logs if the node running the Docker Registry or Minio fails. In most cases this is fine. If you want build images and logs to survive node failures, you can configure the Docker Registry and Minio to use persistent volumes.

    For details on setting up persistent storage for pipelines, refer to this page.

    Example rancher-pipeline.yml​

    An example pipeline configuration file is on this page.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-cluster-tools.html b/v2.5/reference-guides/rancher-cluster-tools.html index fea4e3dc767..aed82efdc96 100644 --- a/v2.5/reference-guides/rancher-cluster-tools.html +++ b/v2.5/reference-guides/rancher-cluster-tools.html @@ -5,13 +5,13 @@ Tools for Logging, Monitoring, and Visibility | Rancher Manager - +
    Version: v2.5

    Tools for Logging, Monitoring, and Visibility

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

    Logging

    Logging is helpful because it allows you to:

    • Capture and analyze the state of your cluster
    • Look for trends in your environment
    • Save your logs to a safe location outside of your cluster
    • Stay informed of events like a container crashing, a pod eviction, or a node dying
    • More easily debugg and troubleshoot problems

    Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

    For more information, refer to the logging documentation here.

    Monitoring and Alerts

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution.

    After monitoring is enabled, you can set up alerts and notifiers that provide the mechanism to receive them.

    Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

    Alerts are rules that trigger those notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

    For more information, refer to the monitoring documentation here.

    Istio

    Istio is an open-source tool that makes it easier for DevOps teams to observe, control, troubleshoot, and secure the traffic within a complex network of microservices.

    Rancher's integration with Istio was improved in Rancher v2.5.

    For more information, refer to the Istio documentation here.

    OPA Gatekeeper

    OPA Gatekeeper is an open-source project that provides integration between OPA and Kubernetes to provide policy control via admission controller webhooks. For details on how to enable Gatekeeper in Rancher, refer to the OPA Gatekeeper section.

    CIS Scans

    Rancher can run a security scan to check whether Kubernetes is deployed according to security best practices as defined in the CIS Kubernetes Benchmark.

    For more information, refer to the CIS scan documentation here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.html b/v2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.html index f983716888d..610b5b21cb6 100644 --- a/v2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.html +++ b/v2.5/reference-guides/rancher-manager-architecture/architecture-recommendations.html @@ -5,13 +5,13 @@ Architecture Recommendations | Rancher Manager - +
    Version: v2.5

    Architecture Recommendations

    Kubernetes cluster. If you are installing Rancher on a single node, the main architecture recommendation that applies to your installation is that the node running Rancher should be separate from downstream clusters.

    Separation of Rancher and User Clusters

    A user cluster is a downstream Kubernetes cluster that runs your apps and services.

    If you have a Docker installation of Rancher, the node running the Rancher server should be separate from your downstream clusters.

    If Rancher is intended to manage downstream Kubernetes clusters, the Kubernetes cluster that the Rancher server runs on should also be separate from the downstream user clusters.

    Separation of Rancher Server from User Clusters

    Why HA is Better for Rancher in Production

    We recommend installing the Rancher server on a high-availability Kubernetes cluster, primarily because it protects the Rancher server data. In a high-availability installation, a load balancer serves as the single point of contact for clients, distributing network traffic across multiple servers in the cluster and helping to prevent any one server from becoming a point of failure.

    We don't recommend installing Rancher in a single Docker container, because if the node goes down, there is no copy of the cluster data available on other nodes and you could lose the data on your Rancher server.

    K3s Kubernetes Cluster Installations​

    One option for the underlying Kubernetes cluster is to use K3s Kubernetes. K3s is Rancher's CNCF certified Kubernetes distribution. It is easy to install and uses half the memory of Kubernetes, all in a binary of less than 100 MB. Another advantage of K3s is that it allows an external datastore to hold the cluster data, allowing the K3s server nodes to be treated as ephemeral.

    Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

    Architecture of a K3s Kubernetes Cluster Running the Rancher Management Server

    RKE Kubernetes Cluster Installations​

    In an RKE installation, the cluster data is replicated on each of three etcd nodes in the cluster, providing redundancy and data duplication in case one of the nodes fails.

    Architecture of an RKE Kubernetes Cluster Running the Rancher Management Server

    Architecture of an RKE Kubernetes cluster running the Rancher management server

    Recommended Load Balancer Configuration for Kubernetes Installations

    We recommend the following configurations for the load balancer and Ingress controllers:

    • The DNS for Rancher should resolve to a Layer 4 load balancer (TCP)
    • The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster.
    • The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443.
    • The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment.
    Rancher installed on a Kubernetes cluster with layer 4 load balancer, depicting SSL termination at Ingress controllers

    Rancher HA

    Environment for Kubernetes Installations

    It is strongly recommended to install Rancher on a Kubernetes cluster on hosted infrastructure such as Amazon's EC2 or Google Compute Engine.

    For the best performance and greater security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    Recommended Node Roles for Kubernetes Installations

    The below recommendations apply when Rancher is installed on a K3s Kubernetes cluster or an RKE Kubernetes cluster.

    K3s Cluster Roles​

    In K3s clusters, there are two types of nodes: server nodes and agent nodes. Both servers and agents can have workloads scheduled on them. Server nodes run the Kubernetes master.

    For the cluster running the Rancher management server, we recommend using two server nodes. Agent nodes are not required.

    RKE Cluster Roles​

    If Rancher is installed on an RKE Kubernetes cluster, the cluster should have three nodes, and each node should have all three Kubernetes roles: etcd, controlplane, and worker.

    Contrasting RKE Cluster Architecture for Rancher Server and for Downstream Kubernetes Clusters​

    Our recommendation for RKE node roles on the Rancher server cluster contrasts with our recommendations for the downstream user clusters that run your apps and services.

    Rancher uses RKE as a library when provisioning downstream Kubernetes clusters. Note: The capability to provision downstream K3s clusters will be added in a future version of Rancher.

    For downstream Kubernetes clusters, we recommend that each node in a user cluster should have a single role for stability and scalability.

    Kubernetes Roles for Nodes in Rancher Server Cluster vs. User Clusters

    RKE only requires at least one node with each role and does not require nodes to be restricted to one role. However, for the clusters that run your apps, we recommend separate roles for each node so that workloads on worker nodes don't interfere with the Kubernetes master or cluster data as your services scale.

    We recommend that downstream user clusters should have at least:

    • Three nodes with only the etcd role to maintain a quorum if one node is lost, making the state of your cluster highly available
    • Two nodes with only the controlplane role to make the master component highly available
    • One or more nodes with only the worker role to run the Kubernetes node components, as well as the workloads for your apps and services

    With that said, it is safe to use all three roles on three nodes when setting up the Rancher server because:

    • It allows one etcd node failure.
    • It maintains multiple instances of the master components by having multiple controlplane nodes.
    • No other workloads than Rancher itself should be created on this cluster.

    Because no additional workloads will be deployed on the Rancher server cluster, in most cases it is not necessary to use the same architecture that we recommend for the scalability and reliability of downstream clusters.

    For more best practices for downstream clusters, refer to the production checklist or our best practices guide.

    Architecture for an Authorized Cluster Endpoint

    If you are using an authorized cluster endpoint, we recommend creating an FQDN pointing to a load balancer which balances traffic across your nodes with the controlplane role.

    If you are using private CA signed certificates on the load balancer, you have to supply the CA certificate, which will be included in the generated kubeconfig file to validate the certificate chain. See the documentation on kubeconfig files and API keys for more information.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html b/v2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html index ea8ecc3860d..6146fa9a25d 100644 --- a/v2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html +++ b/v2.5/reference-guides/rancher-manager-architecture/communicating-with-downstream-user-clusters.html @@ -5,14 +5,14 @@ Communicating with Downstream User Clusters | Rancher Manager - +
    Version: v2.5

    Communicating with Downstream User Clusters

    This section describes how Rancher provisions and manages the downstream user clusters that run your apps and services.

    The below diagram shows how the cluster controllers, cluster agents, and node agents allow Rancher to control downstream clusters.

    Communicating with Downstream Clusters

    Rancher Components

    The following descriptions correspond to the numbers in the diagram above:

    1. The Authentication Proxy
    2. Cluster Controllers and Cluster Agents
    3. Node Agents
    4. Authorized Cluster Endpoint

    1. The Authentication Proxy​

    In this diagram, a user named Bob wants to see all pods running on a downstream user cluster called User Cluster 1. From within Rancher, he can run a kubectl command to see the pods. Bob is authenticated through Rancher's authentication proxy.

    The authentication proxy forwards all Kubernetes API calls to downstream clusters. It integrates with authentication services like local authentication, Active Directory, and GitHub. On every Kubernetes API call, the authentication proxy authenticates the caller and sets the proper Kubernetes impersonation headers before forwarding the call to Kubernetes masters.

    Rancher communicates with Kubernetes clusters using a service account, which provides an identity for processes that run in a pod.

    By default, Rancher generates a kubeconfig file that contains credentials for proxying through the Rancher server to connect to the Kubernetes API server on a downstream user cluster. The kubeconfig file (kube_config_cluster.yml) contains full access to the cluster.

    2. Cluster Controllers and Cluster Agents​

    Each downstream user cluster has a cluster agent, which opens a tunnel to the corresponding cluster controller within the Rancher server.

    There is one cluster controller and one cluster agent for each downstream cluster. Each cluster controller:

    • Watches for resource changes in the downstream cluster
    • Brings the current state of the downstream cluster to the desired state
    • Configures access control policies to clusters and projects
    • Provisions clusters by calling the required Docker machine drivers and Kubernetes engines, such as RKE and GKE

    By default, to enable Rancher to communicate with a downstream cluster, the cluster controller connects to the cluster agent. If the cluster agent is not available, the cluster controller can connect to a node agent instead.

    The cluster agent, also called cattle-cluster-agent, is a component that runs in a downstream user cluster. It performs the following tasks:

    • Connects to the Kubernetes API of Rancher-launched Kubernetes clusters
    • Manages workloads, pod creation and deployment within each cluster
    • Applies the roles and bindings defined in each cluster's global policies
    • Communicates between the cluster and Rancher server (through a tunnel to the cluster controller) about events, stats, node info, and health

    3. Node Agents​

    If the cluster agent (also called cattle-cluster-agent) is not available, one of the node agents creates a tunnel to the cluster controller to communicate with Rancher.

    The cattle-node-agent is deployed using a DaemonSet resource to make sure it runs on every node in a Rancher-launched Kubernetes cluster. It is used to interact with the nodes when performing cluster operations. Examples of cluster operations include upgrading the Kubernetes version and creating or restoring etcd snapshots.

    4. Authorized Cluster Endpoint​

    An authorized cluster endpoint allows users to connect to the Kubernetes API server of a downstream cluster without having to route their requests through the Rancher authentication proxy.

    The authorized cluster endpoint only works on Rancher-launched Kubernetes clusters. In other words, it only works in clusters where Rancher used RKE to provision the cluster. It is not available for registered clusters, or for clusters in a hosted Kubernetes provider, such as Amazon's EKS.

    There are two main reasons why a user might need the authorized cluster endpoint:

    • To access a downstream user cluster while Rancher is down
    • To reduce latency in situations where the Rancher server and downstream cluster are separated by a long distance

    The kube-api-auth microservice is deployed to provide the user authentication functionality for the authorized cluster endpoint. When you access the user cluster using kubectl, the cluster's Kubernetes API server authenticates you by using the kube-api-auth service as a webhook.

    Like the authorized cluster endpoint, the kube-api-auth authentication service is also only available for Rancher-launched Kubernetes clusters.

    Example scenario: Let's say that the Rancher server is located in the United States, and User Cluster 1 is located in Australia. A user, Alice, also lives in Australia. Alice can manipulate resources in User Cluster 1 by using the Rancher UI, but her requests will have to be sent from Australia to the Rancher server in the United States, then be proxied back to Australia, where the downstream user cluster is. The geographical distance may cause significant latency, which Alice can reduce by using the authorized cluster endpoint.

    With this endpoint enabled for the downstream cluster, Rancher generates an extra Kubernetes context in the kubeconfig file in order to connect directly to the cluster. This file has the credentials for kubectl and helm.

    You will need to use a context defined in this kubeconfig file to access the cluster if Rancher goes down. Therefore, we recommend exporting the kubeconfig file so that if Rancher goes down, you can still use the credentials in the file to access your cluster. For more information, refer to the section on accessing your cluster with kubectl and the kubeconfig file.

    Important Files

    The files mentioned below are needed to maintain, troubleshoot and upgrade your cluster:

    • rancher-cluster.yml: The RKE cluster configuration file.
    • kube_config_cluster.yml: The Kubeconfig file for the cluster, this file contains credentials for full access to the cluster. You can use this file to authenticate with a Rancher-launched Kubernetes cluster if Rancher goes down.
    • rancher-cluster.rkestate: The Kubernetes cluster state file. This file contains credentials for full access to the cluster. Note: This state file is only created when using RKE v0.2.0 or higher.

    Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

    For more information on connecting to a cluster without the Rancher authentication proxy and other configuration options, refer to the kubeconfig file documentation.

    Tools for Provisioning Kubernetes Clusters

    The tools that Rancher uses to provision downstream user clusters depends on the type of cluster that is being provisioned.

    Rancher Launched Kubernetes for Nodes Hosted in an Infrastructure Provider​

    Rancher can dynamically provision nodes in a provider such as Amazon EC2, DigitalOcean, Azure, or vSphere, then install Kubernetes on them.

    Rancher provisions this type of cluster using RKE and docker-machine.

    Rancher Launched Kubernetes for Custom Nodes​

    When setting up this type of cluster, Rancher installs Kubernetes on existing nodes, which creates a custom cluster.

    Rancher provisions this type of cluster using RKE.

    Hosted Kubernetes Providers​

    When setting up this type of cluster, Kubernetes is installed by providers such as Google Kubernetes Engine, Amazon Elastic Container Service for Kubernetes, or Azure Kubernetes Service.

    Rancher provisions this type of cluster using kontainer-engine.

    Registered Kubernetes Clusters​

    In this type of cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

    Rancher Server Components and Source Code

    This diagram shows each component that the Rancher server is composed of:

    Rancher Components

    The GitHub repositories for Rancher can be found at the following links:

    This is a partial list of the most important Rancher repositories. For more details about Rancher source code, refer to the section on contributing to Rancher. To see all libraries and projects used in Rancher, see the go.mod file in the rancher/rancher repository.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.html b/v2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.html index f64a955e9e5..729c27adec1 100644 --- a/v2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.html +++ b/v2.5/reference-guides/rancher-manager-architecture/rancher-server-and-components.html @@ -5,13 +5,13 @@ Rancher Server and Components | Rancher Manager - +
    Version: v2.5

    Rancher Server and Components

    The majority of Rancher 2.x software runs on the Rancher Server. Rancher Server includes all the software components used to manage the entire Rancher deployment.

    The figure below illustrates the high-level architecture of Rancher 2.x. The figure depicts a Rancher Server installation that manages two downstream Kubernetes clusters: one created by RKE and another created by Amazon EKS (Elastic Kubernetes Service).

    For the best performance and security, we recommend a dedicated Kubernetes cluster for the Rancher management server. Running user workloads on this cluster is not advised. After deploying Rancher, you can create or import clusters for running your workloads.

    The diagram below shows how users can manipulate both Rancher-launched Kubernetes clusters and hosted Kubernetes clusters through Rancher's authentication proxy:

    Managing Kubernetes Clusters through Rancher's Authentication Proxy

    Architecture

    You can install Rancher on a single node, or on a high-availability Kubernetes cluster.

    A high-availability Kubernetes installation is recommended for production.

    A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:

    The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster..

    The Rancher server, regardless of the installation method, should always run on nodes that are separate from the downstream user clusters that it manages. If Rancher is installed on a high-availability Kubernetes cluster, it should run on a separate cluster from the cluster(s) it manages.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-project-tools.html b/v2.5/reference-guides/rancher-project-tools.html index d78013f95a2..736e27f98c2 100644 --- a/v2.5/reference-guides/rancher-project-tools.html +++ b/v2.5/reference-guides/rancher-project-tools.html @@ -5,13 +5,13 @@ Tools for Logging, Monitoring, and Visibility | Rancher Manager - +
    Version: v2.5

    Tools for Logging, Monitoring, and Visibility

    Rancher contains a variety of tools that aren't included in Kubernetes to assist in your DevOps operations. Rancher can integrate with external services to help your clusters run more efficiently.

    Notifiers and Alerts​

    Notifiers and alerts are two features that work together to inform you of events in the Rancher system. Before they can be enabled, the monitoring application must be installed.

    Notifiers are services that inform you of alert events. You can configure notifiers to send alert notifications to staff best suited to take corrective action. Notifications can be sent with Slack, email, PagerDuty, WeChat, and webhooks.

    Alerts are rules that trigger those notifications. Before you can receive alerts, you must configure one or more notifier in Rancher. The scope for alerts can be set at either the cluster or project level.

    Logging​

    Logging is helpful because it allows you to:

    • Capture and analyze the state of your cluster
    • Look for trends in your environment
    • Save your logs to a safe location outside of your cluster
    • Stay informed of events like a container crashing, a pod eviction, or a node dying
    • More easily debugg and troubleshoot problems

    Rancher can integrate with Elasticsearch, splunk, kafka, syslog, and fluentd.

    For details, refer to the logging section.

    Monitoring​

    Using Rancher, you can monitor the state and processes of your cluster nodes, Kubernetes components, and software deployments through integration with Prometheus, a leading open-source monitoring solution. For details, refer to the monitoring section.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/kubernetes-security-best-practices.html b/v2.5/reference-guides/rancher-security/kubernetes-security-best-practices.html index bfa0a28add4..10d041470e2 100644 --- a/v2.5/reference-guides/rancher-security/kubernetes-security-best-practices.html +++ b/v2.5/reference-guides/rancher-security/kubernetes-security-best-practices.html @@ -5,13 +5,13 @@ Kubernetes Security Best Practices | Rancher Manager - +
    Version: v2.5

    Kubernetes Security Best Practices

    Restricting cloud metadata API access​

    Cloud providers such as AWS, Azure, DigitalOcean or GCP often expose metadata services locally to instances. By default, this endpoint is accessible by pods running on a cloud instance, including pods in hosted Kubernetes providers such as EKS, AKS, DigitalOcean Kubernetes or GKE, and can contain cloud credentials for that node, provisioning data such as kubelet credentials, or other sensitive data. To mitigate this risk when running on a cloud platform, follow the Kubernetes security recommendations: limit permissions given to instance credentials, use network policies to restrict pod access to the metadata API, and avoid using provisioning data to deliver secrets.

    It is advised to consult your cloud provider's security best practices for further recommendations and specific details on how to restrict access to cloud instance metadata API.

    Further references: MITRE ATT&CK knowledge base on - Unsecured Credentials: Cloud Instance Metadata API.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html index 693242c82ff..8b3ac56eab2 100644 --- a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html +++ b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide with CIS 1.5 Benchmark | Rancher Manager - + @@ -33,7 +33,7 @@ RKE Templates are used to provision Kubernetes and define Rancher settings. Foll documentaion for additional installation and RKE Template details.

    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 30
      addons: |-
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: ingress-nginx
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: ingress-nginx
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: ingress-nginx
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: Namespace
        metadata:
          name: cattle-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: default-psp-role
          namespace: cattle-system
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - default-psp
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: default-psp-rolebinding
          namespace: cattle-system
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: default-psp-role
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: policy/v1beta1
        kind: PodSecurityPolicy
        metadata:
          name: restricted
        spec:
          requiredDropCapabilities:
          - NET_RAW
          privileged: false
          allowPrivilegeEscalation: false
          defaultAllowPrivilegeEscalation: false
          fsGroup:
            rule: RunAsAny
          runAsUser:
            rule: MustRunAsNonRoot
          seLinux:
            rule: RunAsAny
          supplementalGroups:
            rule: RunAsAny
          volumes:
          - emptyDir
          - secret
          - persistentVolumeClaim
          - downwardAPI
          - configMap
          - projected
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRole
        metadata:
          name: psp:restricted
        rules:
        - apiGroups:
          - extensions
          resourceNames:
          - restricted
          resources:
          - podsecuritypolicies
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: psp:restricted
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: psp:restricted
        subjects:
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:serviceaccounts
        - apiGroup: rbac.authorization.k8s.io
          kind: Group
          name: system:authenticated
        ---
        apiVersion: v1
        kind: ServiceAccount
        metadata:
          name: tiller
          namespace: kube-system
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: ClusterRoleBinding
        metadata:
          name: tiller
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: cluster-admin
        subjects:
        - kind: ServiceAccount
          name: tiller
          namespace: kube-system
      ignore_docker_version: true
      kubernetes_version: v1.15.9-rancher1-1
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        mtu: 0
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: false
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: '5000'
            heartbeat-interval: '500'
          gid: 52034
          retention: 72h
          snapshot: false
          uid: 52034
        kube_api:
          always_pull_images: false
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube_controller:
          extra_args:
            bind-address: 127.0.0.1
            address: 127.0.0.1
            feature-gates: RotateKubeletServerCertificate=true
            profiling: 'false'
            terminated-pod-gc-threshold: '1000'
        kubelet:
          extra_args:
            anonymous-auth: 'false'
            event-qps: '0'
            feature-gates: RotateKubeletServerCertificate=true
            make-iptables-util-chains: 'true'
            protect-kernel-defaults: 'true'
            streaming-connection-idle-timeout: 1800s
            tls-cipher-suites: >-
              TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          fail_swap_on: false
          generate_serving_certificate: true
        scheduler:
          extra_args:
            bind-address: 127.0.0.1
            address: 127.0.0.1
            profiling: 'false'
      ssh_agent_auth: false
    windows_prefered_cluster: false

    Hardened Reference Ubuntu 18.04 LTS cloud-config:​

    The reference cloud-config is generally used in cloud infrastructure environments to allow for configuration management of compute instances. The reference config configures Ubuntu operating system level settings needed before installing kubernetes.

    #cloud-config
    packages:
      - curl
      - jq
    runcmd:
      - sysctl -w vm.overcommit_memory=1
      - sysctl -w kernel.panic=10
      - sysctl -w kernel.panic_on_oops=1
      - curl https://releases.rancher.com/install-docker/18.09.sh | sh
      - usermod -aG docker ubuntu
      - return=1; while [ $return != 0 ]; do sleep 2; docker ps; return=$?; done
      - addgroup --gid 52034 etcd
      - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd
    write_files:
      - path: /etc/sysctl.d/kubelet.conf
        owner: root:root
        permissions: "0644"
        content: |
          vm.overcommit_memory=1
          kernel.panic=10
          kernel.panic_on_oops=1
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.6-benchmark.html b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.6-benchmark.html index d0c95b6cdd8..5eaf25a9daa 100644 --- a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.6-benchmark.html +++ b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/hardening-guide-with-cis-v1.6-benchmark.html @@ -5,7 +5,7 @@ Hardening Guide with CIS 1.6 Benchmark | Rancher Manager - + @@ -33,7 +33,7 @@ RKE Templates are used to provision Kubernetes and define Rancher settings. Foll documentaion for additional installation and RKE Template details.

    #
    # Cluster Config
    #
    default_pod_security_policy_template_id: restricted
    docker_root_dir: /var/lib/docker
    enable_cluster_alerting: false
    enable_cluster_monitoring: false
    enable_network_policy: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config:
      addon_job_timeout: 45
      ignore_docker_version: true
      kubernetes_version: v1.18.12-rancher1-1
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        mtu: 0
        plugin: canal
      rotate_encryption_key: false
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: false
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: '5000'
            heartbeat-interval: '500'
          gid: 52034
          retention: 72h
          snapshot: false
          uid: 52034
        kube_api:
          always_pull_images: false
          audit_log:
            enabled: true
          event_rate_limit:
            enabled: true
          pod_security_policy: true
          secrets_encryption_config:
            enabled: true
          service_node_port_range: 30000-32767
        kube_controller:
          extra_args:
            feature-gates: RotateKubeletServerCertificate=true
            bind-address: 127.0.0.1
            address: 127.0.0.1
        kubelet:
          extra_args:
            feature-gates: RotateKubeletServerCertificate=true
            protect-kernel-defaults: 'true'
            tls-cipher-suites: >-
              TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256
          fail_swap_on: false
          generate_serving_certificate: true
        scheduler:
          extra_args:
            bind-address: 127.0.0.1
            address: 127.0.0.1
      ssh_agent_auth: false
      upgrade_strategy:
        max_unavailable_controlplane: '1'
        max_unavailable_worker: 10%
    windows_prefered_cluster: false

    Hardened Reference Ubuntu 20.04 LTS cloud-config:​

    The reference cloud-config is generally used in cloud infrastructure environments to allow for configuration management of compute instances. The reference config configures Ubuntu operating system level settings needed before installing kubernetes.

    #cloud-config
    apt:
      sources:
        docker.list:
          source: deb [arch=amd64] http://download.docker.com/linux/ubuntu $RELEASE stable
          keyid: 9DC858229FC7DD38854AE2D88D81803C0EBFCD88
    system_info:
      default_user:
        groups:
        - docker
    write_files:
    - path: "/etc/apt/preferences.d/docker"
      owner: root:root
      permissions: '0600'
      content: |
        Package: docker-ce
        Pin: version 5:19*
        Pin-Priority: 800
    - path: "/etc/sysctl.d/90-kubelet.conf"
      owner: root:root
      permissions: '0644'
      content: |
        vm.overcommit_memory=1
        vm.panic_on_oom=0
        kernel.panic=10
        kernel.panic_on_oops=1
        kernel.keys.root_maxbytes=25000000
    package_update: true
    packages:
    - docker-ce
    - docker-ce-cli
    - containerd.io
    runcmd:
    - sysctl -p /etc/sysctl.d/90-kubelet.conf
    - groupadd --gid 52034 etcd
    - useradd --comment "etcd service account" --uid 52034 --gid 52034 etcd
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html index 8487db3c1ba..c1a8e336325 100644 --- a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html +++ b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.5-benchmark.html @@ -5,7 +5,7 @@ CIS 1.5 Benchmark - Self-Assessment Guide - Rancher v2.5 | Rancher Manager - + @@ -234,7 +234,7 @@ Create a PSP as described in the Kubernetes documentation, ensuring that the Follow the documentation and create NetworkPolicy objects as you need them.

    Audit Script: 5.3.2.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-"/root/.kube/config"}

    kubectl version > /dev/null
    if [ $? -ne 0 ]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    for namespace in $(kubectl get namespaces -A -o json | jq -r '.items[].metadata.name'); do
      policy_count=$(kubectl get networkpolicy -n ${namespace} -o json | jq '.items | length')
      if [ ${policy_count} -eq 0 ]; then
        echo "fail: ${namespace}"
        exit 1
      fi
    done

    echo "pass"

    Audit Execution:

    ./5.3.2.sh

    Expected result:

    'pass' is present

    5.6 General Policies​

    5.6.4 The default namespace should not be used (Scored)​

    Result: PASS

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Audit Script: 5.6.4.sh

    #!/bin/bash -e

    export KUBECONFIG=${KUBECONFIG:-/root/.kube/config}

    kubectl version > /dev/null
    if [[ $? -gt 0 ]]; then
      echo "fail: kubectl failed"
      exit 1
    fi

    default_resources=$(kubectl get all -o json | jq --compact-output '.items[] | select((.kind == "Service") and (.metadata.name == "kubernetes") and (.metadata.namespace == "default") | not)' | wc -l)

    echo "--count=${default_resources}"

    Audit Execution:

    ./5.6.4.sh

    Expected result:

    '0' is equal to '0'
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.6-benchmark.html b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.6-benchmark.html index e4991b89fdc..48106853c4b 100644 --- a/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.6-benchmark.html +++ b/v2.5/reference-guides/rancher-security/rancher-v2.5-hardening-guides/self-assessment-guide-with-cis-v1.6-benchmark.html @@ -5,7 +5,7 @@ CIS 1.6 Benchmark - Self-Assessment Guide - Rancher v2.5.4 | Rancher Manager - + @@ -461,7 +461,7 @@ suggested list of security contexts, you may refer to the CIS Security Benchmark Containers.

    Audit:


    5.7.4 The default namespace should not be used (Automated)​

    Result: pass

    Remediation: Ensure that namespaces are created to allow for appropriate segregation of Kubernetes resources and that all new resources are created in a specific namespace.

    Audit:

    check_for_default_ns.sh

    Expected Result:

    'true' is equal to 'true'

    Audit Script:

    #!/bin/bash

    set -eE

    handle_error() {
        echo "false"
    }

    trap 'handle_error' ERR

    count=$(kubectl get all -n default -o json | jq .items[] | jq -r 'select((.metadata.name!="kubernetes"))' | jq .metadata.name | wc -l)
    if [[ ${count} -gt 0 ]]; then
        echo "false"
        exit
    fi

    echo "true"


    Returned Value:

    true

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/security-advisories-and-cves.html b/v2.5/reference-guides/rancher-security/security-advisories-and-cves.html index 42708ebe354..386f5de92a8 100644 --- a/v2.5/reference-guides/rancher-security/security-advisories-and-cves.html +++ b/v2.5/reference-guides/rancher-security/security-advisories-and-cves.html @@ -5,13 +5,13 @@ Security Advisories and CVEs | Rancher Manager - +
    Version: v2.5

    Security Advisories and CVEs

    Rancher is committed to informing the community of security issues in our products. Rancher will publish security advisories and CVEs (Common Vulnerabilities and Exposures) for issues we have resolved. New security advisories are also published in Rancher's GitHub security page.

    IDDescriptionDateResolution
    CVE-2022-31247An issue was discovered in Rancher versions up to and including 2.5.15 and 2.6.6 where a flaw with authorization logic allows privilege escalation in downstream clusters through cluster role template binding (CRTB) and project role template binding (PRTB). The vulnerability can be exploited by any user who has permissions to create/edit CRTB or PRTB (such as cluster-owner, manage cluster members, project-owner, and manage project members) to gain owner permission in another project in the same cluster or in another project on a different downstream cluster.18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2021-36783It was discovered that in Rancher versions up to and including 2.5.12 and 2.6.3, there is a failure to properly sanitize credentials in cluster template answers. This failure can lead to plaintext storage and exposure of credentials, passwords, and API tokens. The exposed credentials are visible in Rancher to authenticated Cluster Owners, Cluster Members, Project Owners, and Project Members on the endpoints /v1/management.cattle.io.clusters, /v3/clusters, and /k8s/clusters/local/apis/management.cattle.io/v3/clusters.18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2021-36782An issue was discovered in Rancher versions up to and including 2.5.15 and 2.6.6 where sensitive fields like passwords, API keys, and Rancher's service account token (used to provision clusters) were stored in plaintext directly on Kubernetes objects like Clusters (e.g., cluster.management.cattle.io). Anyone with read access to those objects in the Kubernetes API could retrieve the plaintext version of those sensitive data. The issue was partially found and reported by Florian Struck (from Continum AG) and Marco Stuurman (from Shock Media B.V.).18 August 2022Rancher v2.6.7 and Rancher v2.5.16
    CVE-2022-21951This vulnerability only affects customers using Weave Container Network Interface (CNI) when configured through RKE templates. A vulnerability was discovered in Rancher versions 2.5.0 up to and including 2.5.13, and 2.6.0 up to and including 2.6.4, where a user interface (UI) issue with RKE templates does not include a value for the Weave password when Weave is chosen as the CNI. If a cluster is created based on the mentioned template, and Weave is configured as the CNI, no password will be created for network encryption in Weave; therefore, network traffic in the cluster will be sent unencrypted.24 May 2022Rancher v2.6.5 and Rancher v2.5.14
    CVE-2021-36784A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3 which allows users who have create or update permissions on Global Roles to escalate their permissions, or those of another user, to admin-level permissions. Global Roles grant users Rancher-wide permissions, such as the ability to create clusters. In the identified versions of Rancher, when users are given permission to edit or create Global Roles, they are not restricted to only granting permissions which they already posses. This vulnerability affects customers who utilize non-admin users that are able to create or edit Global Roles. The most common use case for this scenario is the restricted-admin role.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    CVE-2021-4200This vulnerability only affects customers using the restricted-admin role in Rancher. A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3 where the global-data role in cattle-global-data namespace grants write access to the Catalogs. Since each user with any level of catalog access was bound to the global-data role, this grants write access to templates (CatalogTemplates) and template versions (CatalogTemplateVersions) for any user with any level of catalog access. New users created in Rancher are by default assigned to the user role (standard user), which is not designed to grant write catalog access. This vulnerability effectively elevates the privilege of any user to write access for the catalog template and catalog template version resources.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    GHSA-wm2r-rp98-8pmhThis vulnerability only affects customers using Fleet for continuous delivery with authenticated Git and/or Helm repositories. An issue was discovered in go-getter library in versions prior to v1.5.11 that exposes SSH private keys in base64 format due to a failure in redacting such information from error messages. The vulnerable version of this library is used in Rancher through Fleet in versions of Fleet prior to v0.3.9. This issue affects Rancher versions 2.5.0 up to and including 2.5.12 and from 2.6.0 up to and including 2.6.3. The issue was found and reported by Dagan Henderson from Raft Engineering.14 Apr 2022Rancher v2.6.4 and Rancher v2.5.13
    CVE-2021-36778A vulnerability was discovered in Rancher versions from 2.5.0 up to and including 2.5.11 and from 2.6.0 up to and including 2.6.2, where an insufficient check of the same-origin policy when downloading Helm charts from a configured private repository can lead to exposure of the repository credentials to a third-party provider. This issue only happens when the user configures access credentials to a private repository in Rancher inside Apps & Marketplace > Repositories. The issue was found and reported by Martin Andreas Ullrich.14 Apr 2022Rancher v2.6.3 and Rancher v2.5.12
    GHSA-hwm2-4ph6-w6m5A vulnerability was discovered in versions of Rancher starting 2.0 up to and including 2.6.3. The restricted pod security policy (PSP) provided in Rancher deviated from the upstream restricted policy provided in Kubernetes on account of which Rancher's PSP had runAsUser set to runAsAny, while upstream had runAsUser set to MustRunAsNonRoot. This allowed containers to run as any user, including a privileged user (root), even when Rancher's restricted policy was enforced on a project or at the cluster level.31 Mar 2022Rancher v2.6.4
    CVE-2021-36775A vulnerability was discovered in Rancher versions up to and including 2.4.17, 2.5.11 and 2.6.2. After removing a Project Role associated with a group from the project, the bindings that granted access to cluster-scoped resources for those subjects were not deleted. This was due to an incomplete authorization logic check. A user who was a member of the affected group with authenticated access to Rancher could exploit this vulnerability to access resources they shouldn't have had access to. The exposure level would depend on the original permission level granted to the affected project role. This vulnerability only affected customers using group based authentication in Rancher.31 Mar 2022Rancher v2.6.3, Rancher v2.5.12 and Rancher v2.4.18
    CVE-2021-36776A vulnerability was discovered in Rancher versions starting 2.5.0 up to and including 2.5.9, that allowed an authenticated user to impersonate any user on a cluster through an API proxy, without requiring knowledge of the impersonated user's credentials. This was due to the API proxy not dropping the impersonation header before sending the request to the Kubernetes API. A malicious user with authenticated access to Rancher could use this to impersonate another user with administrator access in Rancher, thereby gaining administrator level access to the cluster.31 Mar 2022Rancher v2.6.0 and Rancher v2.5.10
    CVE-2021-25318A vulnerability was discovered in Rancher versions 2.0 through the aforementioned fixed versions, where users were granted access to resources regardless of the resource's API group. For example, Rancher should have allowed users access to apps.catalog.cattle.io, but instead incorrectly gave access to apps.*. Resources affected in the Downstream clusters and Rancher management cluster can be found here. There is not a direct mitigation besides upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-31999A vulnerability was discovered in Rancher 2.0.0 through the aforementioned patched versions, where a malicious Rancher user could craft an API request directed at the proxy for the Kubernetes API of a managed cluster to gain access to information they do not have access to. This is done by passing the "Impersonate-User" or "Impersonate-Group" header in the Connection header, which is then correctly removed by the proxy. At this point, instead of impersonating the user and their permissions, the request will act as if it was from the Rancher management server and incorrectly return the information. The vulnerability is limited to valid Rancher users with some level of permissions on the cluster. There is not a direct mitigation besides upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-25320A vulnerability was discovered in Rancher 2.2.0 through the aforementioned patched versions, where cloud credentials weren't being properly validated through the Rancher API. Specifically through a proxy designed to communicate with cloud providers. Any Rancher user that was logged-in and aware of a cloud-credential ID that was valid for a given cloud provider, could call that cloud provider's API through the proxy API, and the cloud-credential would be attached. The exploit is limited to valid Rancher users. There is not a direct mitigation outside of upgrading to the patched Rancher versions.14 Jul 2021Rancher v2.5.9 and Rancher v2.4.16
    CVE-2021-25313A security vulnerability was discovered on all Rancher 2 versions. When accessing the Rancher API with a browser, the URL was not properly escaped, making it vulnerable to an XSS attack. Specially crafted URLs to these API endpoints could include JavaScript which would be embedded in the page and execute in a browser. There is no direct mitigation. Avoid clicking on untrusted links to your Rancher server.2 Mar 2021Rancher v2.5.6, Rancher v2.4.14, and Rancher v2.3.11
    CVE-2019-14435This vulnerability allows authenticated users to potentially extract otherwise private data out of IPs reachable from system service containers used by Rancher. This can include but not only limited to services such as cloud provider metadata services. Although Rancher allow users to configure whitelisted domains for system service access, this flaw can still be exploited by a carefully crafted HTTP request. The issue was found and reported by Matt Belisle and Alex Stevenson at Workiva.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    CVE-2019-14436The vulnerability allows a member of a project that has access to edit role bindings to be able to assign themselves or others a cluster level role granting them administrator access to that cluster. The issue was found and reported by Michal Lipinski at Nokia.5 Aug 2019Rancher v2.2.7 and Rancher v2.1.12
    CVE-2019-13209The vulnerability is known as a Cross-Site Websocket Hijacking attack. This attack allows an exploiter to gain access to clusters managed by Rancher with the roles/permissions of a victim. It requires that a victim to be logged into a Rancher server and then access a third-party site hosted by the exploiter. Once that is accomplished, the exploiter is able to execute commands against the Kubernetes API with the permissions and identity of the victim. Reported by Matt Belisle and Alex Stevenson from Workiva.15 Jul 2019Rancher v2.2.5, Rancher v2.1.11 and Rancher v2.0.16
    CVE-2019-12303Project owners can inject extra fluentd logging configurations that makes it possible to read files or execute arbitrary commands inside the fluentd container. Reported by Tyler Welton from Untamed Theory.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-12274Nodes using the built-in node drivers using a file path option allows the machine to read arbitrary files including sensitive ones from inside the Rancher server container.5 Jun 2019Rancher v2.2.4, Rancher v2.1.10 and Rancher v2.0.15
    CVE-2019-11202The default admin, that is shipped with Rancher, will be re-created upon restart of Rancher despite being explicitly deleted.16 Apr 2019Rancher v2.2.2, Rancher v2.1.9 and Rancher v2.0.14
    CVE-2019-6287Project members continue to get access to namespaces from projects that they were removed from if they were added to more than one project.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11
    CVE-2018-20321Any project member with access to the default namespace can mount the netes-default service account in a pod and then use that pod to execute administrative privileged commands against the Kubernetes cluster.29 Jan 2019Rancher v2.1.6 and Rancher v2.0.11 - Rolling back from these versions or greater have specific instructions.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html b/v2.5/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html index 437de28afd8..246c6624918 100644 --- a/v2.5/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html +++ b/v2.5/reference-guides/rancher-security/selinux-rpm/about-rancher-selinux.html @@ -5,13 +5,13 @@ About rancher-selinux | Rancher Manager - +
    Version: v2.5

    About rancher-selinux

    To allow Rancher to work with SELinux, some functionality has to be manually enabled for the SELinux nodes. To help with that, Rancher provides a SELinux RPM.

    The rancher-selinux RPM only contains policies for the rancher-logging application.

    The rancher-selinux GitHub repository is here.

    Installing the rancher-selinux RPM​

    Requirement:

    The rancher-selinux RPM was tested with CentOS 7 and 8.

    1. Set up the yum repo​

    Set up the yum repo to install rancher-selinux directly on all hosts in the cluster.

    In order to use the RPM repository, on a CentOS 7 or RHEL 7 system, run the following bash snippet:

    # cat << EOF > /etc/yum.repos.d/rancher.repo 
    [rancher] 
    name=Rancher 
    baseurl=https://rpm.rancher.io/rancher/production/centos/7/noarch
    enabled=1 
    gpgcheck=1 
    gpgkey=https://rpm.rancher.io/public.key 
    EOF

    In order to use the RPM repository, on a CentOS 8 or RHEL 8 system, run the following bash snippet:

    # cat << EOF > /etc/yum.repos.d/rancher.repo 
    [rancher] 
    name=Rancher 
    baseurl=https://rpm.rancher.io/rancher/production/centos/8/noarch
    enabled=1 
    gpgcheck=1 
    gpgkey=https://rpm.rancher.io/public.key 
    EOF

    2. Installing the RPM​

    Install the RPM:

    yum -y install rancher-selinux

    Configuring the Logging Application to Work with SELinux​

    Requirement:

    Logging v2 was tested with SELinux on RHEL/CentOS 7 and 8.

    Applications do not automatically work once the rancher-selinux RPM is installed on the host. They need to be configured to run in an allowed SELinux container domain provided by the RPM.

    To configure the rancher-logging chart to be SELinux aware, change global.seLinux.enabled to true in the values.yaml when installing the chart.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html b/v2.5/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html index 221af08a06c..33575483561 100644 --- a/v2.5/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html +++ b/v2.5/reference-guides/rancher-security/selinux-rpm/about-rke2-selinux.html @@ -5,13 +5,13 @@ About rke2-selinux | Rancher Manager - +
    Version: v2.5

    About rke2-selinux

    rke2-selinux provides policies for RKE2. It is installed automatically when the RKE2 installer script detects that it is running on an RPM-based distro.

    The rke2-selinux GitHub repository is here.

    For more information about installing RKE2 on SELinux-enabled hosts, see the RKE2 documentation.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/rke1-template-example-yaml.html b/v2.5/reference-guides/rke1-template-example-yaml.html index 6c664c44060..66ba6f813d4 100644 --- a/v2.5/reference-guides/rke1-template-example-yaml.html +++ b/v2.5/reference-guides/rke1-template-example-yaml.html @@ -5,13 +5,13 @@ RKE1 Example YAML | Rancher Manager - +
    Version: v2.5

    RKE1 Example YAML

    Below is an example RKE template configuration file for reference.

    The YAML in the RKE template uses the same customization that is used when you create an RKE cluster. However, since the YAML is within the context of a Rancher provisioned RKE cluster, the customization from the RKE docs needs to be nested under the rancher_kubernetes_engine directive.

    #
    # Cluster Config
    #
    docker_root_dir: /var/lib/docker

    enable_cluster_alerting: false
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have alerting turned off by default,
    # but end users could still turn alerting
    # on or off.

    enable_cluster_monitoring: true
    # This setting is not enforced. Clusters
    # created with this sample template
    # would have monitoring turned on
    # by default, but end users could still
    # turn monitoring on or off.

    enable_network_policy: false
    local_cluster_auth_endpoint:
      enabled: true
    #
    # Rancher Config
    #
    rancher_kubernetes_engine_config: # Your RKE template config goes here.
      addon_job_timeout: 30
      authentication:
        strategy: x509
      ignore_docker_version: true
    #
    # # Currently only nginx ingress provider is supported.
    # # To disable ingress controller, set `provider: none`
    # # To enable ingress on specific nodes, use the node_selector, eg:
    #    provider: nginx
    #    node_selector:
    #      app: ingress
    #
      ingress:
        provider: nginx
      kubernetes_version: v1.15.3-rancher3-1
      monitoring:
        provider: metrics-server
    #
    #   If you are using calico on AWS
    #
    #    network:
    #      plugin: calico
    #      calico_network_provider:
    #        cloud_provider: aws
    #
    # # To specify flannel interface
    #
    #    network:
    #      plugin: flannel
    #      flannel_network_provider:
    #      iface: eth1
    #
    # # To specify flannel interface for canal plugin
    #
    #    network:
    #      plugin: canal
    #      canal_network_provider:
    #        iface: eth1
    #
      network:
        options:
          flannel_backend_type: vxlan
        plugin: canal
    #
    #    services:
    #      kube-api:
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kube-controller:
    #        cluster_cidr: 10.42.0.0/16
    #        service_cluster_ip_range: 10.43.0.0/16
    #      kubelet:
    #        cluster_domain: cluster.local
    #        cluster_dns_server: 10.43.0.10
    #
      services:
        etcd:
          backup_config:
            enabled: true
            interval_hours: 12
            retention: 6
            safe_timestamp: false
          creation: 12h
          extra_args:
            election-timeout: 5000
            heartbeat-interval: 500
          gid: 0
          retention: 72h
          snapshot: false
          uid: 0
        kube_api:
          always_pull_images: false
          pod_security_policy: false
          service_node_port_range: 30000-32767
      ssh_agent_auth: false
    windows_prefered_cluster: false
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/single-node-rancher-in-docker/advanced-options.html b/v2.5/reference-guides/single-node-rancher-in-docker/advanced-options.html index 5e00761ab6f..397f10d3f47 100644 --- a/v2.5/reference-guides/single-node-rancher-in-docker/advanced-options.html +++ b/v2.5/reference-guides/single-node-rancher-in-docker/advanced-options.html @@ -5,13 +5,13 @@ Advanced Options for Docker Installs | Rancher Manager - +
    Version: v2.5

    Advanced Options for Docker Installs

    When installing Rancher, there are several advanced options that can be enabled:

    Custom CA Certificate​

    If you want to configure Rancher to use a CA root certificate to be used when validating services, you would start the Rancher container sharing the directory that contains the CA root certificate.

    Use the command example to start a Rancher container with your private CA certificates mounted.

    • The volume flag (-v) should specify the host directory containing the CA root certificates.
    • The environment variable flag (-e) in combination with SSL_CERT_DIR and directory declares an environment variable that specifies the mounted CA root certificates directory location inside the container.
    • Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE.
    • Mounting a host directory inside the container can be done using -v host-source-directory:container-destination-directory or --volume host-source-directory:container-destination-directory.

    The example below is based on having the CA root certificates in the /host/certs directory on the host and mounting this directory on /container/certs inside the Rancher container.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /host/certs:/container/certs \
      -e SSL_CERT_DIR="/container/certs" \
      --privileged \
      rancher/rancher:latest

    API Audit Log​

    The API Audit Log records all the user and system transactions made through Rancher server.

    The API Audit Log writes to /var/log/auditlog inside the rancher container by default. Share that directory as a volume and set your AUDIT_LEVEL to enable the log.

    See API Audit Log for more information and options.

    As of Rancher v2.5, privileged access is required.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /var/log/rancher/auditlog:/var/log/auditlog \
      -e AUDIT_LEVEL=1 \
      --privileged \
      rancher/rancher:latest

    TLS settings​

    To set a different TLS configuration, you can use the CATTLE_TLS_MIN_VERSION and CATTLE_TLS_CIPHERS environment variables. For example, to configure TLS 1.0 as minimum accepted TLS version:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e CATTLE_TLS_MIN_VERSION="1.0" \
      --privileged \
      rancher/rancher:latest

    As of Rancher v2.5, privileged access is required.

    See TLS settings for more information and options.

    Air Gap​

    If you are visiting this page to complete an air gap installation, you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

    Example:

     <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

    Persistent Data​

    Rancher uses etcd as a datastore. When Rancher is installed with Docker, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher.

    You can bind mount a host volume to this location to preserve data on the host it is running on:

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -v /opt/rancher:/var/lib/rancher \
      --privileged \
      rancher/rancher:latest

    As of Rancher v2.5, privileged access is required.

    Running rancher/rancher and rancher/rancher-agent on the Same Node​

    In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the rancher/rancher container.

    If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advise to expose for the rancher/rancher container.

    Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes.

    To change the host ports mapping, replace the following part -p 80:80 -p 443:443 with -p 8080:80 -p 8443:443:

    docker run -d --restart=unless-stopped \
      -p 8080:80 -p 8443:443 \
      --privileged \
      rancher/rancher:latest

    As of Rancher v2.5, privileged access is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html b/v2.5/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html index 3dadb09cd18..7ffbfc85b8a 100644 --- a/v2.5/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html +++ b/v2.5/reference-guides/single-node-rancher-in-docker/http-proxy-configuration.html @@ -5,13 +5,13 @@ HTTP Proxy Configuration | Rancher Manager - +
    Version: v2.5

    HTTP Proxy Configuration

    If you operate Rancher behind a proxy and you want to access services through the proxy (such as retrieving catalogs), you must provide Rancher information about your proxy. As Rancher is written in Go, it uses the common proxy environment variables as shown below.

    Make sure NO_PROXY contains the network addresses, network address ranges and domains that should be excluded from using the proxy.

    Environment variablePurpose
    HTTP_PROXYProxy address to use when initiating HTTP connection(s)
    HTTPS_PROXYProxy address to use when initiating HTTPS connection(s)
    NO_PROXYNetwork address(es), network address range(s) and domains to exclude from using the proxy when initiating connection(s)

    Note NO_PROXY must be in uppercase to use network range (CIDR) notation.

    Docker Installation​

    Passing environment variables to the Rancher container can be done using -e KEY=VALUE or --env KEY=VALUE. Required values for NO_PROXY in a Docker Installation are:

    • localhost
    • 127.0.0.1
    • 0.0.0.0
    • 10.0.0.0/8
    • cattle-system.svc
    • .svc
    • .cluster.local

    The example below is based on a proxy server accessible at http://192.168.0.1:3128, and excluding usage the proxy when accessing network range 192.168.10.0/24 and every hostname under the domain example.com.

    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      -e HTTP_PROXY="http://192.168.10.1:3128" \
      -e HTTPS_PROXY="http://192.168.10.1:3128" \
      -e NO_PROXY="localhost,127.0.0.1,0.0.0.0,10.0.0.0/8,cattle-system.svc,192.168.10.0/24,.svc,.cluster.local,example.com" \
      --privileged \
      rancher/rancher:latest

    As of Rancher v2.5, privileged access is required.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/system-tools.html b/v2.5/reference-guides/system-tools.html index c88959dae82..17ee874b79f 100644 --- a/v2.5/reference-guides/system-tools.html +++ b/v2.5/reference-guides/system-tools.html @@ -5,14 +5,14 @@ System Tools | Rancher Manager - +
    Version: v2.5

    System Tools

    System Tools is a tool to perform operational tasks on Rancher Launched Kubernetes clusters or installations of Rancher on an RKE cluster. The tasks include:

    • Collect logging and system metrics from nodes.
    • Remove Kubernetes resources created by Rancher.

    The following commands are available:

    CommandDescription
    logsCollect Kubernetes cluster component logs from nodes.
    statsStream system metrics from nodes.
    removeRemove Kubernetes resources created by Rancher.

    Download System Tools

    You can download the latest version of System Tools from the GitHub releases page. Download the version of system-tools for the OS that you are using to interact with the cluster.

    Operating SystemFilename
    MacOSsystem-tools_darwin-amd64
    Linuxsystem-tools_linux-amd64
    Windowssystem-tools_windows-amd64.exe

    After you download the tools, complete the following actions:

    1. Rename the file to system-tools.

    2. Give the file executable permissions by running the following command:

      Using Windows? The file is already an executable, you can skip this step.

      chmod +x system-tools

    Logs

    The logs subcommand will collect log files of core Kubernetes cluster components from nodes in Rancher-launched Kubernetes clusters or nodes on an RKE Kubernetes cluster that Rancher is installed on.. See Troubleshooting for a list of core Kubernetes cluster components.

    System Tools will use the provided kubeconfig file to deploy a DaemonSet, that will copy all the logfiles from the core Kubernetes cluster components and add them to a single tar file (cluster-logs.tar by default). If you only want to collect logging from a single node, you can specify the node by using --node NODENAME or -n NODENAME.

    Usage​

    ./system-tools_darwin-amd64 logs --kubeconfig <KUBECONFIG>

    The following are the options for the logs command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file.
    --output <FILENAME>, -o cluster-logs.tarName of the created tarball containing the logs. If no output filename is defined, the options defaults to cluster-logs.tar.
    --node <NODENAME>, -n node1Specify the nodes to collect the logs from. If no node is specified, logs from all nodes in the cluster will be collected.

    Stats

    The stats subcommand will display system metrics from nodes in Rancher-launched Kubernetes clusters or nodes in an RKE Kubernetes cluster that Rancher is installed on..

    System Tools will deploy a DaemonSet, and run a predefined command based on sar (System Activity Report) to show system metrics.

    Usage​

    ./system-tools_darwin-amd64 stats --kubeconfig <KUBECONFIG>

    The following are the options for the stats command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file.
    --node <NODENAME>, -n node1Specify the nodes to display the system metrics from. If no node is specified, logs from all nodes in the cluster will be displayed.
    --stats-command value, -s valueThe command to run to display the system metrics. If no command is defined, the options defaults to /usr/bin/sar -u -r -F 1 1.

    Remove

    Warning: This command will remove data from your etcd nodes. Make sure you have created a backup of etcd before executing the command.

    When you install Rancher on a Kubernetes cluster, it will create Kubernetes resources to run and to store configuration data. If you want to remove Rancher from your cluster, you can use the remove subcommand to remove the Kubernetes resources. When you use the remove subcommand, the following resources will be removed:

    • The Rancher deployment namespace (cattle-system by default).
    • Any serviceAccount, clusterRoles, and clusterRoleBindings that Rancher applied the cattle.io/creator:norman label to. Rancher applies this label to any resource that it creates.
    • Labels, annotations, and finalizers.
    • Rancher Deployment.
    • Machines, clusters, projects, and user custom resource deployments (CRDs).
    • All resources create under the management.cattle.io API Group.
    • All CRDs created by Rancher v2.x.

    Using 2.0.8 or Earlier?

    These versions of Rancher do not automatically delete the serviceAccount, clusterRole, and clusterRoleBindings resources after the job runs. You'll have to delete them yourself.

    Usage​

    When you run the command below, all the resources listed above will be removed from the cluster.

    Warning: This command will remove data from your etcd nodes. Make sure you have created a backup of etcd before executing the command.

    ./system-tools remove --kubeconfig <KUBECONFIG> --namespace <NAMESPACE>

    The following are the options for the remove command:

    OptionDescription
    --kubeconfig <KUBECONFIG_PATH>, -c <KUBECONFIG_PATH>The cluster's kubeconfig file
    --namespace <NAMESPACE>, -n cattle-systemRancher 2.x deployment namespace (<NAMESPACE>). If no namespace is defined, the options defaults to cattle-system.
    --forceSkips the interactive removal confirmation and removes the Rancher deployment without prompt.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/user-settings/api-keys.html b/v2.5/reference-guides/user-settings/api-keys.html index cc7f0740b34..f4229e0347d 100644 --- a/v2.5/reference-guides/user-settings/api-keys.html +++ b/v2.5/reference-guides/user-settings/api-keys.html @@ -5,13 +5,13 @@ API Keys | Rancher Manager - +
    Version: v2.5

    API Keys

    API Keys and User Authentication​

    If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI.

    An API key is also required for using Rancher CLI.

    API Keys are composed of four components:

    • Endpoint: This is the IP address and path that other applications use to send requests to the Rancher API.
    • Access Key: The token's username.
    • Secret Key: The token's password. For applications that prompt you for two different strings for API authentication, you usually enter the two keys together.
    • Bearer Token: The token username and password concatenated together. Use this string for applications that prompt you for one authentication string.

    Creating an API Key​

    1. Select User Avatar > API & Keys from the User Settings menu in the upper-right.

    2. Click Add Key.

    3. Optional: Enter a description for the API key and select an expiration period or a scope. We recommend setting an expiration date.

      The API key won't be valid after expiration. Shorter expiration periods are more secure.

      Expiration period will be bound by v3/settings/auth-token-max-ttl-minutes. If it exceeds the max-ttl, API key will be created with max-ttl as the expiration period.

      A scope will limit the API key so that it will only work against the Kubernetes API of the specified cluster. If the cluster is configured with an Authorized Cluster Endpoint, you will be able to use a scoped token directly against the cluster's API without proxying through the Rancher server. See Authorized Cluster Endpoints for more information.

    4. Click Create.

      Step Result: Your API Key is created. Your API Endpoint, Access Key, Secret Key, and Bearer Token are displayed.

      Use the Bearer Token to authenticate with Rancher CLI.

    5. Copy the information displayed to a secure location. This information is only displayed once, so if you lose your key, you'll have to make a new one.

    What's Next?​

    • Enter your API key information into the application that will send requests to the Rancher API.
    • Learn more about the Rancher endpoints and parameters by selecting View in API for an object in the Rancher UI.
    • API keys are used for API calls and Rancher CLI.

    Deleting API Keys​

    If you need to revoke an API key, delete it. You should delete API keys:

    • That may have been compromised.
    • That have expired.

    To delete an API, select the stale key and click Delete.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/user-settings/manage-cloud-credentials.html b/v2.5/reference-guides/user-settings/manage-cloud-credentials.html index 658aa8a16b3..1dcbd4b03f7 100644 --- a/v2.5/reference-guides/user-settings/manage-cloud-credentials.html +++ b/v2.5/reference-guides/user-settings/manage-cloud-credentials.html @@ -5,13 +5,13 @@ Managing Cloud Credentials | Rancher Manager - +
    Version: v2.5

    Managing Cloud Credentials

    When you create a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node.

    Node templates can use cloud credentials to access the credential information required to provision nodes in the infrastructure providers. The same cloud credential can be used by multiple node templates. By using a cloud credential, you do not have to re-enter access keys for the same cloud provider. Cloud credentials are stored as Kubernetes secrets.

    Cloud credentials are only used by node templates if there are fields marked as password. The default active node drivers have their account access fields marked as password, but there may be some inactive node drivers, which are not using them yet. These node drivers will not use cloud credentials.

    You can create cloud credentials in two contexts:

    All cloud credentials are bound to the user profile of who created it. They cannot be shared across users.

    Creating a Cloud Credential from User Settings​

    1. From your user settings, select User Avatar > Cloud Credentials.
    2. Click Add Cloud Credential.
    3. Enter a name for the cloud credential.
    4. Select a Cloud Credential Type from the drop down. The values of this dropdown is based on the active node drivers in Rancher.
    5. Based on the selected cloud credential type, enter the required values to authenticate with the infrastructure provider.
    6. Click Create.

    Result: The cloud credential is created and can immediately be used to create node templates.

    Updating a Cloud Credential​

    When access credentials are changed or compromised, updating a cloud credential allows you to rotate those credentials while keeping the same node template.

    1. From your user settings, select User Avatar > Cloud Credentials.
    2. Choose the cloud credential you want to edit and click the ⋮ > Edit.
    3. Update the credential information and click Save.

    Result: The cloud credential is updated with the new access credentials. All existing node templates using this cloud credential will automatically use the updated information whenever new nodes are added.

    Deleting a Cloud Credential​

    In order to delete cloud credentials, there must not be any node template associated with it. If you are unable to delete the cloud credential, delete any node templates that are still associated to that cloud credential.

    1. From your user settings, select User Avatar > Cloud Credentials.

    2. You can either individually delete a cloud credential or bulk delete.

      • To individually delete one, choose the cloud credential you want to edit and click the ⋮ > Delete.
      • To bulk delete cloud credentials, select one or more cloud credentials from the list. Click Delete.

    3. Confirm that you want to delete these cloud credentials.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/user-settings/manage-node-templates.html b/v2.5/reference-guides/user-settings/manage-node-templates.html index 0fca7ed7bfa..53edfcbd1cd 100644 --- a/v2.5/reference-guides/user-settings/manage-node-templates.html +++ b/v2.5/reference-guides/user-settings/manage-node-templates.html @@ -5,13 +5,13 @@ Managing Node Templates | Rancher Manager - +
    Version: v2.5

    Managing Node Templates

    When you provision a cluster hosted by an infrastructure provider, node templates are used to provision the cluster nodes. These templates use Docker Machine configuration options to define an operating system image and settings/parameters for the node. You can create node templates in two contexts:

    When you create a node template, it is bound to your user profile. Node templates cannot be shared among users. You can delete stale node templates that you no longer user from your user settings.

    Creating a Node Template from User Settings​

    1. From your user settings, select User Avatar > Node Templates.
    2. Click Add Template.
    3. Select one of the cloud providers available. Then follow the instructions on screen to configure the template.

    Result: The template is configured. You can use the template later when you provision a node pool cluster.

    Updating a Node Template​

    1. From your user settings, select User Avatar > Node Templates.

    2. Choose the node template that you want to edit and click the ⋮ > Edit.

      note

      As of v2.2.0, the default active node drivers and any node driver, that has fields marked as password, are required to use cloud credentials. If you have upgraded to v2.2.0, existing node templates will continue to work with the previous account access information, but when you edit the node template, you will be required to create a cloud credential and the node template will start using it.

    3. Edit the required information and click Save.

    Result: The node template is updated. All node pools using this node template will automatically use the updated information when new nodes are added.

    Cloning Node Templates​

    When creating new node templates from your user settings, you can clone an existing template and quickly update its settings rather than creating a new one from scratch. Cloning templates saves you the hassle of re-entering access keys for the cloud provider.

    1. From your user settings, select User Avatar > Node Templates.
    2. Find the template you want to clone. Then select ⋮ > Clone.
    3. Complete the rest of the form.

    Result: The template is cloned and configured. You can use the template later when you provision a node pool cluster.

    Deleting a Node Template​

    When you no longer use a node template, you can delete it from your user settings.

    1. From your user settings, select User Avatar > Node Templates.
    2. Select one or more template from the list. Then click Delete. Confirm the delete when prompted.
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/reference-guides/user-settings/user-preferences.html b/v2.5/reference-guides/user-settings/user-preferences.html index e38264f8bc6..2166b2b51cc 100644 --- a/v2.5/reference-guides/user-settings/user-preferences.html +++ b/v2.5/reference-guides/user-settings/user-preferences.html @@ -5,13 +5,13 @@ User Preferences | Rancher Manager - +
    Version: v2.5

    User Preferences

    Each user can choose preferences to personalize their Rancher experience. To change preference settings, open the User Settings menu and then select Preferences.

    The preferences available will differ depending on whether the User Settings menu was accessed while on the Cluster Manager UI or the Cluster Explorer UI.

    Theme​

    Choose your background color for the Rancher UI. If you choose Auto, the background color changes from light to dark at 6 PM, and then changes back at 6 AM.

    My Account​

    This section displays the Name (your display name) and Username (your login) used for your session. To change your login's current password, click the Change Password button.

    Table Row per Page​

    On pages that display system objects like clusters or deployments in a table, you can set the number of objects that display on the page before you must paginate. The default setting is 50.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/security/security-scan.html b/v2.5/security/security-scan.html index d8d5b7bd696..2ae6b7cff4c 100644 --- a/v2.5/security/security-scan.html +++ b/v2.5/security/security-scan.html @@ -5,13 +5,13 @@ Security Scans | Rancher Manager - +
    Version: v2.5

    Security Scans

    The documentation about CIS security scans has moved here.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting.html b/v2.5/troubleshooting.html index ea7f2c1efa4..41b7cf26d97 100644 --- a/v2.5/troubleshooting.html +++ b/v2.5/troubleshooting.html @@ -5,13 +5,13 @@ Troubleshooting | Rancher Manager - +
    Version: v2.5

    Troubleshooting

    This section contains information to help you troubleshoot issues when using Rancher.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html b/v2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html index bebce2a94bc..69581637eef 100644 --- a/v2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html +++ b/v2.5/troubleshooting/kubernetes-components/troubleshooting-controlplane-nodes.html @@ -5,13 +5,13 @@ Troubleshooting Controlplane Nodes | Rancher Manager - +
    Version: v2.5

    Troubleshooting Controlplane Nodes

    This section applies to nodes with the controlplane role.

    Check if the Controlplane Containers are Running

    There are three specific containers launched on nodes with the controlplane role:

    • kube-apiserver
    • kube-controller-manager
    • kube-scheduler

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kube-apiserver|kube-controller-manager|kube-scheduler'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    26c7159abbcc        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-apiserver
    f3d287ca4549        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-scheduler
    bdf3898b8063        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-controller-manager

    Controlplane Container Logging

    Note: If you added multiple nodes with the controlplane role, both kube-controller-manager and kube-scheduler use a leader election process to determine the leader. Only the current leader will log the performed actions. See Kubernetes leader election how to retrieve the current leader.

    The logging of the containers can contain information on what the problem could be.

    docker logs kube-apiserver
    docker logs kube-controller-manager
    docker logs kube-scheduler
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html b/v2.5/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html index 62ef9d35464..1af94efe7ec 100644 --- a/v2.5/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html +++ b/v2.5/troubleshooting/kubernetes-components/troubleshooting-etcd-nodes.html @@ -5,13 +5,13 @@ Troubleshooting etcd Nodes | Rancher Manager - +
    Version: v2.5

    Troubleshooting etcd Nodes

    This section contains commands and tips for troubleshooting nodes with the etcd role.

    Checking if the etcd Container is Running​

    The container for etcd should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=etcd$

    Example output:

    CONTAINER ID        IMAGE                         COMMAND                  CREATED             STATUS              PORTS               NAMES
    605a124503b9        rancher/coreos-etcd:v3.2.18   "/usr/local/bin/et..."   2 hours ago         Up 2 hours                              etcd

    etcd Container Logging​

    The logging of the container can contain information on what the problem could be.

    docker logs etcd
    LogExplanation
    health check for peer xxx could not connect: dial tcp IP:2380: getsockopt: connection refusedA connection to the address shown on port 2380 cannot be established. Check if the etcd container is running on the host with the address shown.
    xxx is starting a new election at term xThe etcd cluster has lost its quorum and is trying to establish a new leader. This can happen when the majority of the nodes running etcd go down/unreachable.
    connection error: desc = "transport: Error while dialing dial tcp 0.0.0.0:2379: i/o timeout"; Reconnecting to {0.0.0.0:2379 0 <nil>}The host firewall is preventing network communication.
    rafthttp: request cluster ID mismatchThe node with the etcd instance logging rafthttp: request cluster ID mismatch is trying to join a cluster that has already been formed with another peer. The node should be removed from the cluster, and re-added.
    rafthttp: failed to find memberThe cluster state (/var/lib/etcd) contains wrong information to join the cluster. The node should be removed from the cluster, the state directory should be cleaned and the node should be re-added.

    etcd Cluster and Connectivity Checks​

    The address where etcd is listening depends on the address configuration of the host etcd is running on. If an internal address is configured for the host etcd is running on, the endpoint for etcdctl needs to be specified explicitly. If any of the commands respond with Error: context deadline exceeded, the etcd instance is unhealthy (either quorum is lost or the instance is not correctly joined in the cluster)

    Check etcd Members on all Nodes​

    Output should contain all the nodes with the etcd role and the output should be identical on all nodes.

    Command:

    docker exec etcd etcdctl member list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list"

    Example output:

    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001
    xxx, started, etcd-xxx, https://IP:2380, https://IP:2379,https://IP:4001

    Check Endpoint Status​

    The values for RAFT TERM should be equal and RAFT INDEX should be not be too far apart from each other.

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 | 333ef673fc4add56 |  3.2.18 |   24 MB |     false |        72 |      66887 |
    | https://IP:2379 | 5feed52d940ce4cf |  3.2.18 |   24 MB |      true |        72 |      66887 |
    | https://IP:2379 | db6b3bdb559a848d |  3.2.18 |   25 MB |     false |        72 |      66887 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Check Endpoint Health​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint health

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl endpoint health --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")

    Example output:

    https://IP:2379 is healthy: successfully committed proposal: took = 2.113189ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.649963ms
    https://IP:2379 is healthy: successfully committed proposal: took = 2.451201ms

    Check Connectivity on Port TCP/2379​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5"); do
       echo "Validating connection to ${endpoint}/health"
       docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5"); do
      echo "Validating connection to ${endpoint}/health";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/health"
    done

    Example output:

    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}
    Validating connection to https://IP:2379/health
    {"health": "true"}

    Check Connectivity on Port TCP/2380​

    Command:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    for endpoint in $(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f4"); do
      echo "Validating connection to ${endpoint}/version";
      docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl --http1.1 -s -w "\n" --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) "${endpoint}/version"
    done

    Example output:

    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}
    Validating connection to https://IP:2380/version
    {"etcdserver":"3.2.18","etcdcluster":"3.2.0"}

    etcd Alarms​

    etcd will trigger alarms, for instance when it runs out of space.

    Command:

    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output when NOSPACE alarm is triggered:

    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE

    etcd Space Errors​

    Related error messages are etcdserver: mvcc: database space exceeded or applying raft message exceeded backend quota. Alarm NOSPACE will be triggered.

    Resolutions:

    Compact the Keyspace​

    Command:

    rev=$(docker exec etcd etcdctl endpoint status --write-out json | egrep -o '"revision":[0-9]*' | egrep -o '[0-9]*')
    docker exec etcd etcdctl compact "$rev"

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    rev=$(docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT endpoint status --write-out json | egrep -o '\"revision\":[0-9]*' | egrep -o '[0-9]*'")
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT compact \"$rev\""

    Example output:

    compacted revision xxx

    Defrag All etcd Members​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl defrag

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl defrag --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','")"

    Example output:

    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]
    Finished defragmenting etcd member[https://IP:2379]

    Check Endpoint Status​

    Command:

    docker exec -e ETCDCTL_ENDPOINTS=$(docker exec etcd /bin/sh -c "etcdctl member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") etcd etcdctl endpoint status --write-out table

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl endpoint status --endpoints=$(docker exec etcd /bin/sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT member list | cut -d, -f5 | sed -e 's/ //g' | paste -sd ','") --write-out table"

    Example output:

    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | ENDPOINT        |        ID        | VERSION | DB SIZE | IS LEADER | RAFT TERM | RAFT INDEX |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+
    | https://IP:2379 |  e973e4419737125 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | 4a509c997b26c206 |  3.2.18 |  553 kB |     false |        32 |    2449410 |
    | https://IP:2379 | b217e736575e9dd3 |  3.2.18 |  553 kB |      true |        32 |    2449410 |
    +-----------------+------------------+---------+---------+-----------+-----------+------------+

    Disarm Alarm​

    After verifying that the DB size went down after compaction and defragmenting, the alarm needs to be disarmed for etcd to allow writes again.

    Command:

    docker exec etcd etcdctl alarm list
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm disarm"
    docker exec etcd sh -c "etcdctl --endpoints=\$ETCDCTL_ENDPOINT alarm list"

    Example output:

    docker exec etcd etcdctl alarm list
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    memberID:x alarm:NOSPACE
    docker exec etcd etcdctl alarm disarm
    docker exec etcd etcdctl alarm list

    Log Level​

    The log level of etcd can be changed dynamically via the API. You can configure debug logging using the commands below.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"DEBUG"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    To reset the log level back to the default (INFO), you can use the following command.

    Command:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINTS)/config/local/log

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker run --net=host -v $(docker inspect kubelet --format '{{ range .Mounts }}{{ if eq .Destination "/etc/kubernetes" }}{{ .Source }}{{ end }}{{ end }}')/ssl:/etc/kubernetes/ssl:ro appropriate/curl -s -XPUT -d '{"Level":"INFO"}' --cacert $(docker exec etcd printenv ETCDCTL_CACERT) --cert $(docker exec etcd printenv ETCDCTL_CERT) --key $(docker exec etcd printenv ETCDCTL_KEY) $(docker exec etcd printenv ETCDCTL_ENDPOINT)/config/local/log

    etcd Content​

    If you want to investigate the contents of your etcd, you can either watch streaming events or you can query etcd directly, see below for examples.

    Watch Streaming Events​

    Command:

    docker exec etcd etcdctl watch --prefix /registry

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT watch --prefix /registry

    If you only want to see the affected keys (and not the binary data), you can append | grep -a ^/registry to the command to filter for keys only.

    Query etcd Directly​

    Command:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only

    Command when using etcd version lower than 3.3.x (Kubernetes 1.13.x and lower) and --internal-address was specified when adding the node:

    docker exec etcd etcdctl --endpoints=\$ETCDCTL_ENDPOINT get /registry --prefix=true --keys-only

    You can process the data to get a summary of count per key, using the command below:

    docker exec etcd etcdctl get /registry --prefix=true --keys-only | grep -v ^$ | awk -F'/' '{ if ($3 ~ /cattle.io/) {h[$3"/"$4]++} else { h[$3]++ }} END { for(k in h) print h[k], k }' | sort -nr

    Replacing Unhealthy etcd Nodes​

    When a node in your etcd cluster becomes unhealthy, the recommended approach is to fix or remove the failed or unhealthy node before adding a new etcd node to the cluster.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html b/v2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html index ac8a1a2f896..2e3d106c446 100644 --- a/v2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html +++ b/v2.5/troubleshooting/kubernetes-components/troubleshooting-nginx-proxy.html @@ -5,13 +5,13 @@ Troubleshooting nginx-proxy | Rancher Manager - +
    Version: v2.5

    Troubleshooting nginx-proxy

    The nginx-proxy container is deployed on every node that does not have the controlplane role. It provides access to all the nodes with the controlplane role by dynamically generating the NGINX configuration based on available nodes with the controlplane role.

    Check if the Container is Running

    The container is called nginx-proxy and should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name=nginx-proxy

    Example output:

    docker ps -a -f=name=nginx-proxy
    CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS               NAMES
    c3e933687c0e        rancher/rke-tools:v0.1.15   "nginx-proxy CP_HO..."   3 hours ago         Up 3 hours                              nginx-proxy

    Check Generated NGINX Configuration

    The generated configuration should include the IP addresses of the nodes with the controlplane role. The configuration can be checked using the following command:

    docker exec nginx-proxy cat /etc/nginx/nginx.conf

    Example output:

    error_log stderr notice;

    worker_processes auto;
    events {
      multi_accept on;
      use epoll;
      worker_connections 1024;
    }

    stream {
            upstream kube_apiserver {

                server ip_of_controlplane_node1:6443;

                server ip_of_controlplane_node2:6443;

            }

            server {
                listen        6443;
                proxy_pass    kube_apiserver;
                proxy_timeout 30;
                proxy_connect_timeout 2s;

            }

    }

    nginx-proxy Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs nginx-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html b/v2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html index 1ae8f3c047c..8edb49002e5 100644 --- a/v2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html +++ b/v2.5/troubleshooting/kubernetes-components/troubleshooting-worker-nodes-and-generic-components.html @@ -5,13 +5,13 @@ Troubleshooting Worker Nodes and Generic Components | Rancher Manager - +
    Version: v2.5

    Troubleshooting Worker Nodes and Generic Components

    This section applies to every node as it includes components that run on nodes with any role.

    Check if the Containers are Running

    There are two specific containers launched on nodes with the worker role:

    • kubelet
    • kube-proxy

    The containers should have status Up. The duration shown after Up is the time the container has been running.

    docker ps -a -f=name='kubelet|kube-proxy'

    Example output:

    CONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES
    158d0dcc33a5        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kube-proxy
    a30717ecfb55        rancher/hyperkube:v1.11.5-rancher1   "/opt/rke-tools/en..."   3 hours ago         Up 3 hours                              kubelet

    Container Logging

    The logging of the containers can contain information on what the problem could be.

    docker logs kubelet
    docker logs kube-proxy
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/dns.html b/v2.5/troubleshooting/other-troubleshooting-tips/dns.html index 45d444ab33e..53df1ca25a7 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/dns.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/dns.html @@ -5,13 +5,13 @@ DNS | Rancher Manager - +
    Version: v2.5

    DNS

    The commands/steps listed on this page can be used to check name resolution issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Before running the DNS checks, check the default DNS provider for your cluster and make sure that the overlay network is functioning correctly as this can also be the reason why DNS resolution (partly) fails.

    Check if DNS pods are running​

    kubectl -n kube-system get pods -l k8s-app=kube-dns

    Example output when using CoreDNS:

    NAME                       READY   STATUS    RESTARTS   AGE
    coredns-799dffd9c4-6jhlz   1/1     Running   0          76m

    Example output when using kube-dns:

    NAME                        READY   STATUS    RESTARTS   AGE
    kube-dns-5fd74c7488-h6f7n   3/3     Running   0          4m13s

    Check if the DNS service is present with the correct cluster-ip​

    kubectl -n kube-system get svc -l k8s-app=kube-dns
    NAME               TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)         AGE
    service/kube-dns   ClusterIP   10.43.0.10   <none>        53/UDP,53/TCP   4m13s

    Check if domain names are resolving​

    Check if internal cluster names are resolving (in this example, kubernetes.default), the IP shown after Server: should be the same as the CLUSTER-IP from the kube-dns service.

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup kubernetes.default

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      kubernetes.default
    Address 1: 10.43.0.1 kubernetes.default.svc.cluster.local
    pod "busybox" deleted

    Check if external names are resolving (in this example, www.google.com)

    kubectl run -it --rm --restart=Never busybox --image=busybox:1.28 -- nslookup www.google.com

    Example output:

    Server:    10.43.0.10
    Address 1: 10.43.0.10 kube-dns.kube-system.svc.cluster.local

    Name:      www.google.com
    Address 1: 2a00:1450:4009:80b::2004 lhr35s04-in-x04.1e100.net
    Address 2: 216.58.211.100 ams15s32-in-f4.1e100.net
    pod "busybox" deleted

    If you want to check resolving of domain names on all of the hosts, execute the following steps:

    1. Save the following file as ds-dnstest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: dnstest
      spec:
        selector:
            matchLabels:
              name: dnstest
        template:
          metadata:
            labels:
              name: dnstest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: busybox:1.28
              imagePullPolicy: Always
              name: alpine
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f ds-dnstest.yml

    3. Wait until kubectl rollout status ds/dnstest -w returns: daemon set "dnstest" successfully rolled out.

    4. Configure the environment variable DOMAIN to a fully qualified domain name (FQDN) that the host should be able to resolve (www.google.com is used as an example) and run the following command to let each container on every host resolve the configured domain name (it's a single line command).

      export DOMAIN=www.google.com; echo "=> Start DNS resolve test"; kubectl get pods -l name=dnstest --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do kubectl exec $pod -- /bin/sh -c "nslookup $DOMAIN > /dev/null 2>&1"; RC=$?; if [ $RC -ne 0 ]; then echo $host cannot resolve $DOMAIN; fi; done; echo "=> End DNS resolve test"

    5. When this command has finished running, the output indicating everything is correct is:

      => Start DNS resolve test
      => End DNS resolve test

    If you see error in the output, that means that the mentioned host(s) is/are not able to resolve the given FQDN.

    Example error output of a situation where host with IP 209.97.182.150 had the UDP ports blocked.

    => Start DNS resolve test
    command terminated with exit code 1
    209.97.182.150 cannot resolve www.google.com
    => End DNS resolve test

    Cleanup the alpine DaemonSet by running kubectl delete ds/dnstest.

    CoreDNS specific​

    Check CoreDNS logging​

    kubectl -n kube-system logs -l k8s-app=kube-dns

    Check configuration​

    CoreDNS configuration is stored in the configmap coredns in the kube-system namespace.

    kubectl -n kube-system get configmap coredns -o go-template={{.data.Corefile}}

    Check upstream nameservers in resolv.conf​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for CoreDNS. You can check this file on the host or run the following Pod with dnsPolicy set to Default, which will inherit the /etc/resolv.conf from the host it is running on.

    kubectl run -i --restart=Never --rm test-${RANDOM} --image=ubuntu --overrides='{"kind":"Pod", "apiVersion":"v1", "spec": {"dnsPolicy":"Default"}}' -- sh -c 'cat /etc/resolv.conf'

    Enable query logging​

    Enabling query logging can be done by enabling the log plugin in the Corefile configuration in the configmap coredns. You can do so by using kubectl -n kube-system edit configmap coredns or use the command below to replace the configuration in place:

    kubectl get configmap -n kube-system coredns -o json | sed -e 's_loadbalance_log\\n    loadbalance_g' | kubectl apply -f -

    All queries will now be logged and can be checked using the command in Check CoreDNS logging.

    kube-dns specific​

    Check upstream nameservers in kubedns container​

    By default, the configured nameservers on the host (in /etc/resolv.conf) will be used as upstream nameservers for kube-dns. Sometimes the host will run a local caching DNS nameserver, which means the address in /etc/resolv.conf will point to an address in the loopback range (127.0.0.0/8) which will be unreachable by the container. In case of Ubuntu 18.04, this is done by systemd-resolved. We detect if systemd-resolved is running, and will automatically use the /etc/resolv.conf file with the correct upstream nameservers (which is located at /run/systemd/resolve/resolv.conf).

    Use the following command to check the upstream nameservers used by the kubedns container:

    kubectl -n kube-system get pods -l k8s-app=kube-dns --no-headers -o custom-columns=NAME:.metadata.name,HOSTIP:.status.hostIP | while read pod host; do echo "Pod ${pod} on host ${host}"; kubectl -n kube-system exec $pod -c kubedns cat /etc/resolv.conf; done

    Example output:

    Pod kube-dns-667c7cb9dd-z4dsf on host x.x.x.x
    nameserver 1.1.1.1
    nameserver 8.8.4.4

    If the output shows an address in the loopback range (127.0.0.0/8), you can correct this in two ways:

    • Make sure the correct nameservers are listed in /etc/resolv.conf on your nodes in the cluster, please consult your operating system documentation on how to do this. Make sure you execute this before provisioning a cluster, or reboot the nodes after making the modification.
    • Configure the kubelet to use a different file for resolving names, by using extra_args as shown below (where /run/resolvconf/resolv.conf is the file with the correct nameservers):
    services:
      kubelet:
        extra_args:
          resolv-conf: "/run/resolvconf/resolv.conf"

    Note: As the kubelet is running inside a container, the path for files located in /etc and /usr are in /host/etc and /host/usr inside the kubelet container.

    See Editing Cluster as YAML how to apply this change. When the provisioning of the cluster has finished, you have to remove the kube-dns pod to activate the new setting in the pod:

    kubectl delete pods -n kube-system -l k8s-app=kube-dns
    pod "kube-dns-5fd74c7488-6pwsf" deleted

    Try to resolve name again using Check if domain names are resolving.

    If you want to check the kube-dns configuration in your cluster (for example, to check if there are different upstream nameservers configured), you can run the following command to list the kube-dns configuration:

    kubectl -n kube-system get configmap kube-dns -o go-template='{{range $key, $value := .data}}{{ $key }}{{":"}}{{ $value }}{{"\n"}}{{end}}'

    Example output:

    upstreamNameservers:["1.1.1.1"]
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html b/v2.5/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html index a9110d8c3e4..16dc9ca767c 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/expired-webhook-certificate-rotation.html @@ -5,13 +5,13 @@ Rotation of Expired Webhook Certificates | Rancher Manager - +
    Version: v2.5

    Rotation of Expired Webhook Certificates

    For Rancher versions that have rancher-webhook installed, certain versions created certificates that will expire after one year. It will be necessary for you to rotate your webhook certificate if the certificate did not renew.

    In Rancher v2.5.12 and up, rancher-webhook deployments will automatically renew their TLS certificate when it is within 30 or fewer days of its expiration date. If you are using v2.5.11 or below, there are two methods to work around this issue:

    1. Users with cluster access, run the following commands:​
    kubectl delete secret -n cattle-system cattle-webhook-tls
    kubectl delete mutatingwebhookconfigurations.admissionregistration.k8s.io --ignore-not-found=true rancher.cattle.io
    kubectl delete pod -n cattle-system -l app=rancher-webhook
    2. Users with no cluster access via kubectl:​

    1. Delete the cattle-webhook-tls secret in the cattle-system namespace in the local cluster.

    2. Delete the rancher.cattle.io mutating webhook

    3. Delete the rancher-webhook pod in the cattle-system namespace in the local cluster.

    Note: The webhook certificate expiration issue is not specific to cattle-webhook-tls as listed in the examples. You will fill in your expired certificate secret accordingly.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html b/v2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html index 72ad8699311..ef01f260bdd 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/kubernetes-resources.html @@ -5,13 +5,13 @@ Kubernetes resources | Rancher Manager - +
    Version: v2.5

    Kubernetes resources

    The commands/steps listed on this page can be used to check the most important Kubernetes resources and apply to Rancher Launched Kubernetes clusters.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Nodes​

    Get nodes​

    Run the command below and check the following:

    • All nodes in your cluster should be listed, make sure there is not one missing.
    • All nodes should have the Ready status (if not in Ready state, check the kubelet container logs on that node using docker logs kubelet)
    • Check if all nodes report the correct version.
    • Check if OS/Kernel/Docker values are shown as expected (possibly you can relate issues due to upgraded OS/Kernel/Docker)
    kubectl get nodes -o wide

    Example output:

    NAME             STATUS   ROLES          AGE   VERSION   INTERNAL-IP      EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION      CONTAINER-RUNTIME
    controlplane-0   Ready    controlplane   31m   v1.13.5   138.68.188.91    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    etcd-0           Ready    etcd           31m   v1.13.5   138.68.180.33    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5
    worker-0         Ready    worker         30m   v1.13.5   139.59.179.88    <none>        Ubuntu 18.04.2 LTS   4.15.0-47-generic   docker://18.9.5

    Get node conditions​

    Run the command below to list nodes with Node Conditions

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{end}}'

    Run the command below to list nodes with Node Conditions that are active that could prevent normal operation.

    kubectl get nodes -o go-template='{{range .items}}{{$node := .}}{{range .status.conditions}}{{if ne .type "Ready"}}{{if eq .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{":"}}{{.status}}{{"\n"}}{{end}}{{else}}{{if ne .status "True"}}{{$node.metadata.name}}{{": "}}{{.type}}{{": "}}{{.status}}{{"\n"}}{{end}}{{end}}{{end}}{{end}}'

    Example output:

    worker-0: DiskPressure:True

    Kubernetes leader election​

    Kubernetes Controller Manager leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-controller-manager endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-controller-manager -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Kubernetes Scheduler leader​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the kube-scheduler endpoint (in this example, controlplane-0).

    kubectl -n kube-system get endpoints kube-scheduler -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"controlplane-0_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","leaseDurationSeconds":15,"acquireTime":"2018-12-27T08:59:45Z","renewTime":"2018-12-27T09:44:57Z","leaderTransitions":0}>

    Ingress Controller​

    The default Ingress Controller is NGINX and is deployed as a DaemonSet in the ingress-nginx namespace. The pods are only scheduled to nodes with the worker role.

    Check if the pods are running on all nodes:

    kubectl -n ingress-nginx get pods -o wide

    Example output:

    kubectl -n ingress-nginx get pods -o wide
    NAME                                    READY     STATUS    RESTARTS   AGE       IP               NODE
    default-http-backend-797c5bc547-kwwlq   1/1       Running   0          17m       x.x.x.x          worker-1
    nginx-ingress-controller-4qd64          1/1       Running   0          14m       x.x.x.x          worker-1
    nginx-ingress-controller-8wxhm          1/1       Running   0          13m       x.x.x.x          worker-0

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n ingress-nginx describe pods -l app=ingress-nginx

    Pod container logs​

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    Namespace events​

    kubectl -n ingress-nginx get events

    Debug logging​

    To enable debug logging:

    kubectl -n ingress-nginx patch ds nginx-ingress-controller --type='json' -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--v=5"}]'

    Check configuration​

    Retrieve generated configuration in each pod:

    kubectl -n ingress-nginx get pods -l app=ingress-nginx --no-headers -o custom-columns=.NAME:.metadata.name | while read pod; do kubectl -n ingress-nginx exec $pod -- cat /etc/nginx/nginx.conf; done

    Rancher agents

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes (cluster provisioning via cattle-node-agent) is done through Rancher agents.

    cattle-node-agent​

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent

    Jobs and Pods​

    Check that pods or jobs have status Running/Completed​

    To check, run the command:

    kubectl get pods --all-namespaces

    If a pod is not in Running state, you can dig into the root cause by running:

    Describe pod​

    kubectl describe pod POD_NAME -n NAMESPACE

    Pod container logs​

    kubectl logs POD_NAME -n NAMESPACE

    If a job is not in Completed state, you can dig into the root cause by running:

    Describe job​

    kubectl describe job JOB_NAME -n NAMESPACE

    Logs from the containers of pods of the job​

    kubectl logs -l job-name=JOB_NAME -n NAMESPACE

    Evicted pods​

    Pods can be evicted based on eviction signals.

    Retrieve a list of evicted pods (podname and namespace):

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}'

    To delete all evicted pods:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace delete pod $epod; done

    Retrieve a list of evicted pods, scheduled node and the reason:

    kubectl get pods --all-namespaces -o go-template='{{range .items}}{{if eq .status.phase "Failed"}}{{if eq .status.reason "Evicted"}}{{.metadata.name}}{{" "}}{{.metadata.namespace}}{{"\n"}}{{end}}{{end}}{{end}}' | while read epod enamespace; do kubectl -n $enamespace get pod $epod -o=custom-columns=NAME:.metadata.name,NODE:.spec.nodeName,MSG:.status.message; done

    Job does not complete​

    If you have enabled Istio, and you are having issues with a Job you deployed not completing, you will need to add an annotation to your pod using these steps.

    Since Istio Sidecars run indefinitely, a Job cannot be considered complete even after its task has completed. This is a temporary workaround and will disable Istio for any traffic to/from the annotated Pod. Keep in mind this may not allow you to continue to use a Job for integration testing, as the Job will not have access to the service mesh.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/logging.html b/v2.5/troubleshooting/other-troubleshooting-tips/logging.html index 8f51be6b756..b5fb755d81b 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/logging.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/logging.html @@ -5,13 +5,13 @@ Logging | Rancher Manager - +
    Version: v2.5

    Logging

    The following log levels are used in Rancher:

    NameDescription
    infoLogs informational messages. This is the default log level.
    debugLogs more detailed messages that can be used to debug.
    traceLogs very detailed messages on internal functions. This is very verbose and can contain sensitive information.

    How to configure a log level​

    • Kubernetes install
    • Configure debug log level
    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set debug; done
    OK
    OK
    OK
    $ kubectl -n cattle-system logs -l app=rancher -c rancher
    • Configure info log level
    $ KUBECONFIG=./kube_config_cluster.yml
    $ kubectl -n cattle-system get pods -l app=rancher --no-headers -o custom-columns=name:.metadata.name | while read rancherpod; do kubectl -n cattle-system exec $rancherpod -c rancher -- loglevel --set info; done
    OK
    OK
    OK
    • Docker Install
    • Configure debug log level
    $ docker exec -ti <container_id> loglevel --set debug
    OK
    $ docker logs -f <container_id>
    • Configure info log level
    $ docker exec -ti <container_id> loglevel --set info
    OK
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/networking.html b/v2.5/troubleshooting/other-troubleshooting-tips/networking.html index 0b725bdcb62..cd0a8da9241 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/networking.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/networking.html @@ -5,13 +5,13 @@ Networking | Rancher Manager - +
    Version: v2.5

    Networking

    The commands/steps listed on this page can be used to check networking related issues in your cluster.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml for Rancher HA) or are using the embedded kubectl via the UI.

    Double check if all the required ports are opened in your (host) firewall​

    Double check if all the required ports are opened in your (host) firewall. The overlay network uses UDP in comparison to all other required ports which are TCP.

    Check if overlay network is functioning correctly​

    The pod can be scheduled to any of the hosts you used for your cluster, but that means that the NGINX ingress controller needs to be able to route the request from NODE_1 to NODE_2. This happens over the overlay network. If the overlay network is not functioning, you will experience intermittent TCP/HTTP connection failures due to the NGINX ingress controller not being able to route to the pod.

    To test the overlay network, you can launch the following DaemonSet definition. This will run a swiss-army-knife container on every host (image was developed by Rancher engineers and can be found here: https://github.com/rancherlabs/swiss-army-knife), which we will use to run a ping test between containers on all hosts.

    Note: This container does not support ARM nodes, such as a Raspberry Pi. This will be seen in the pod logs as exec user process caused: exec format error.

    1. Save the following file as overlaytest.yml

      apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: overlaytest
      spec:
        selector:
            matchLabels:
              name: overlaytest
        template:
          metadata:
            labels:
              name: overlaytest
          spec:
            tolerations:
            - operator: Exists
            containers:
            - image: rancherlabs/swiss-army-knife
              imagePullPolicy: Always
              name: overlaytest
              command: ["sh", "-c", "tail -f /dev/null"]
              terminationMessagePath: /dev/termination-log

    2. Launch it using kubectl create -f overlaytest.yml

    3. Wait until kubectl rollout status ds/overlaytest -w returns: daemon set "overlaytest" successfully rolled out.

    4. Run the following script, from the same location. It will have each overlaytest container on every host ping each other:

      #!/bin/bash
      echo "=> Start network overlay test"
        kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.metadata.name}{" "}{@.spec.nodeName}{"\n"}{end}' |
        while read spod shost
          do kubectl get pods -l name=overlaytest -o jsonpath='{range .items[*]}{@.status.podIP}{" "}{@.spec.nodeName}{"\n"}{end}' |
          while read tip thost
            do kubectl --request-timeout='10s' exec $spod -c overlaytest -- /bin/sh -c "ping -c2 $tip > /dev/null 2>&1"
              RC=$?
              if [ $RC -ne 0 ]
                then echo FAIL: $spod on $shost cannot reach pod IP $tip on $thost
                else echo $shost can reach $thost
              fi
          done
        done
      echo "=> End network overlay test"

    5. When this command has finished running, it will output the state of each route:

      => Start network overlay test
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.7.3 on wk2
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.0.5 on cp1
      Error from server (NotFound): pods "wk2" not found
      FAIL: overlaytest-5bglp on wk2 cannot reach pod IP 10.42.2.12 on wk1
      command terminated with exit code 1
      FAIL: overlaytest-v4qkl on cp1 cannot reach pod IP 10.42.7.3 on wk2
      cp1 can reach cp1
      cp1 can reach wk1
      command terminated with exit code 1
      FAIL: overlaytest-xpxwp on wk1 cannot reach pod IP 10.42.7.3 on wk2
      wk1 can reach cp1
      wk1 can reach wk1
      => End network overlay test

      If you see error in the output, there is some issue with the route between the pods on the two hosts. In the above output the node wk2 has no connectivity over the overlay network. This could be because the required ports for overlay networking are not opened for wk2.

    6. You can now clean up the DaemonSet by running kubectl delete ds/overlaytest.

    Check if MTU is correctly configured on hosts and on peering/tunnel appliances/devices​

    When the MTU is incorrectly configured (either on hosts running Rancher, nodes in created/imported clusters or on appliances/devices in between), error messages will be logged in Rancher and in the agents, similar to:

    • websocket: bad handshake
    • Failed to connect to proxy
    • read tcp: i/o timeout

    See Google Cloud VPN: MTU Considerations for an example how to configure MTU correctly when using Google Cloud VPN between Rancher and cluster nodes.

    Resolved issues​

    Overlay network broken when using Canal/Flannel due to missing node annotations​

    GitHub issue#13644
    Resolved inv2.1.2

    To check if your cluster is affected, the following command will list nodes that are broken (this command requires jq to be installed):

    kubectl get nodes -o json | jq '.items[].metadata | select(.annotations["flannel.alpha.coreos.com/public-ip"] == null or .annotations["flannel.alpha.coreos.com/kube-subnet-manager"] == null or .annotations["flannel.alpha.coreos.com/backend-type"] == null or .annotations["flannel.alpha.coreos.com/backend-data"] == null) | .name'

    If there is no output, the cluster is not affected.

    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/rancher-ha.html b/v2.5/troubleshooting/other-troubleshooting-tips/rancher-ha.html index b0853cdd427..2d8dba274da 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/rancher-ha.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/rancher-ha.html @@ -5,13 +5,13 @@ Rancher HA | Rancher Manager - +
    Version: v2.5

    Rancher HA

    The commands/steps listed on this page can be used to check your Rancher Kubernetes Installation.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kube_config_cluster.yml).

    Check Rancher pods​

    Rancher pods are deployed as a Deployment in the cattle-system namespace.

    Check if the pods are running on all nodes:

    kubectl -n cattle-system get pods -l app=rancher -o wide

    Example output:

    NAME                       READY   STATUS    RESTARTS   AGE   IP          NODE
    rancher-7dbd7875f7-n6t5t   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qbj5k   1/1     Running   0          8m    x.x.x.x     x.x.x.x
    rancher-7dbd7875f7-qw7wb   1/1     Running   0          8m    x.x.x.x     x.x.x.x

    If a pod is unable to run (Status is not Running, Ready status is not showing 1/1 or you see a high count of Restarts), check the pod details, logs and namespace events.

    Pod details​

    kubectl -n cattle-system describe pods -l app=rancher

    Pod container logs​

    kubectl -n cattle-system logs -l app=rancher

    Namespace events​

    kubectl -n cattle-system get events

    Check ingress​

    Ingress should have the correct HOSTS (showing the configured FQDN) and ADDRESS (host address(es) it will be routed to).

    kubectl -n cattle-system get ingress

    Example output:

    NAME      HOSTS                    ADDRESS                   PORTS     AGE
    rancher   rancher.yourdomain.com   x.x.x.x,x.x.x.x,x.x.x.x   80, 443   2m

    Check ingress controller logs​

    When accessing your configured Rancher FQDN does not show you the UI, check the ingress controller logging to see what happens when you try to access Rancher:

    kubectl -n ingress-nginx logs -l app=ingress-nginx

    Leader election​

    The leader is determined by a leader election process. After the leader has been determined, the leader (holderIdentity) is saved in the cattle-controllers ConfigMap (in this example, rancher-7dbd7875f7-qbj5k).

    kubectl -n kube-system get configmap cattle-controllers -o jsonpath='{.metadata.annotations.control-plane\.alpha\.kubernetes\.io/leader}'
    {"holderIdentity":"rancher-7dbd7875f7-qbj5k","leaseDurationSeconds":45,"acquireTime":"2019-04-04T11:53:12Z","renewTime":"2019-04-04T12:24:08Z","leaderTransitions":0}
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/v2.5/troubleshooting/other-troubleshooting-tips/registered-clusters.html b/v2.5/troubleshooting/other-troubleshooting-tips/registered-clusters.html index 57551d50e78..d34051319a7 100644 --- a/v2.5/troubleshooting/other-troubleshooting-tips/registered-clusters.html +++ b/v2.5/troubleshooting/other-troubleshooting-tips/registered-clusters.html @@ -5,13 +5,13 @@ Registered clusters | Rancher Manager - +
    Version: v2.5

    Registered clusters

    The commands/steps listed on this page can be used to check clusters that you are registering or that are registered in Rancher.

    Make sure you configured the correct kubeconfig (for example, export KUBECONFIG=$PWD/kubeconfig_from_imported_cluster.yml)

    Rancher agents​

    Communication to the cluster (Kubernetes API via cattle-cluster-agent) and communication to the nodes is done through Rancher agents.

    If the cattle-cluster-agent cannot connect to the configured server-url, the cluster will remain in Pending state, showing Waiting for full cluster configuration.

    cattle-node-agent​

    Note: Starting in Rancher 2.5 cattle-node-agents are only present in clusters created in Rancher with RKE.

    Check if the cattle-node-agent pods are present on each node, have status Running and don't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-agent -o wide

    Example output:

    NAME                      READY     STATUS    RESTARTS   AGE       IP                NODE
    cattle-node-agent-4gc2p   1/1       Running   0          2h        x.x.x.x           worker-1
    cattle-node-agent-8cxkk   1/1       Running   0          2h        x.x.x.x           etcd-1
    cattle-node-agent-kzrlg   1/1       Running   0          2h        x.x.x.x           etcd-0
    cattle-node-agent-nclz9   1/1       Running   0          2h        x.x.x.x           controlplane-0
    cattle-node-agent-pwxp7   1/1       Running   0          2h        x.x.x.x           worker-0
    cattle-node-agent-t5484   1/1       Running   0          2h        x.x.x.x           controlplane-1
    cattle-node-agent-t8mtz   1/1       Running   0          2h        x.x.x.x           etcd-2

    Check logging of a specific cattle-node-agent pod or all cattle-node-agent pods:

    kubectl -n cattle-system logs -l app=cattle-agent

    cattle-cluster-agent​

    Check if the cattle-cluster-agent pod is present in the cluster, has status Running and doesn't have a high count of Restarts:

    kubectl -n cattle-system get pods -l app=cattle-cluster-agent -o wide

    Example output:

    NAME                                    READY     STATUS    RESTARTS   AGE       IP           NODE
    cattle-cluster-agent-54d7c6c54d-ht9h4   1/1       Running   0          2h        x.x.x.x      worker-1

    Check logging of cattle-cluster-agent pod:

    kubectl -n cattle-system logs -l app=cattle-cluster-agent
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file diff --git a/versions.html b/versions.html index 3ab2743f5a5..57eac14e39c 100644 --- a/versions.html +++ b/versions.html @@ -5,13 +5,13 @@ Rancher Documentation Versions | Rancher Manager - +

    Current versions​

    Below are the documentation and release notes for the currently released version of Rancher 2.6.x:

    v2.6.8DocumentationRelease NotesSupport Matrix

    Below are the documentation and release notes for the currently released version of Rancher 2.5.x:

    v2.5.16DocumentationRelease NotesSupport Matrix

    Past versions​

    Below are the documentation and release notes for previous versions of Rancher 2.6.x:

    v2.6.7DocumentationRelease NotesSupport Matrix
    v2.6.6DocumentationRelease NotesSupport Matrix
    v2.6.5DocumentationRelease NotesSupport Matrix
    v2.6.4DocumentationRelease NotesSupport Matrix
    v2.6.3DocumentationRelease NotesSupport Matrix
    v2.6.2DocumentationRelease NotesSupport Matrix
    v2.6.1DocumentationRelease NotesSupport Matrix
    v2.6.0DocumentationRelease NotesSupport Matrix

    Below are the documentation and release notes for previous versions of Rancher 2.5.x:

    v2.5.15DocumentationRelease NotesSupport Matrix
    v2.5.14DocumentationRelease NotesSupport Matrix
    v2.5.13DocumentationRelease NotesSupport Matrix
    v2.5.12DocumentationRelease NotesSupport Matrix
    v2.5.11DocumentationRelease NotesSupport Matrix
    v2.5.10DocumentationRelease NotesSupport Matrix
    v2.5.9DocumentationRelease NotesSupport Matrix
    v2.5.8DocumentationRelease NotesSupport Matrix
    v2.5.7DocumentationRelease NotesSupport Matrix
    v2.5.6DocumentationRelease NotesSupport Matrix
    v2.5.5DocumentationRelease NotesSupport Matrix
    v2.5.4DocumentationRelease NotesSupport Matrix
    v2.5.3DocumentationRelease NotesSupport Matrix
    v2.5.2DocumentationRelease NotesSupport Matrix
    v2.5.1DocumentationRelease NotesSupport Matrix
    v2.5.0DocumentationRelease NotesSupport Matrix

    Legacy versions (EOL)​

    Below is the documentation for legacy versions of Rancher 2.0 - 2.4.x:

    v2.0 - v2.4Documentation
    Copyright © 2022 SUSE Rancher. All Rights Reserved.
    - + \ No newline at end of file